[PATCH 0/2] docs: A couple of small changes to system/arm/cpu-features

[PATCH 0/2] docs: A couple of small changes to system/arm/cpu-features

[Kashyap Chamarthy]

One is a trivial, mechanical change to consistenlty use "vCPU".  The
other updates some details about the "PAuth" (Pointer Authentication)
feature.

I replaced the "TCG vCPU Features" heading with "PAuth" because of this:
before this change, the section says, it is about "CPU features that are
specific to TCG".  But it has only PAuth-related parameters under it.
Since PAuth is relevant to both KVM and TCG, I moved them under a
separate PAuth section, instead of duplicating it.

But now we have a small inconsistency - there's a KVM-only CPU features
section, but no TCG-only section.  I thought when there are more
TCG-only CPU features, that section can be added back in.  Or I can add
that back in, if anyone feels strongly about it.

Kashyap Chamarthy (2):
  docs/cpu-features: Consistently use vCPU instead of VCPU
  docs/cpu-features: Update "PAuth" (Pointer Authentication) details

 docs/system/arm/cpu-features.rst | 37 ++++++++++++++++++++++----------
 1 file changed, 26 insertions(+), 11 deletions(-)

-- 
2.48.1

[PATCH 1/2] docs/cpu-features: Consistently use vCPU instead of VCPU

[Kashyap Chamarthy]

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/system/arm/cpu-features.rst | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/system/arm/cpu-features.rst b/docs/system/arm/cpu-features.rst
index a5fb929243c..78f18c87a81 100644
--- a/docs/system/arm/cpu-features.rst
+++ b/docs/system/arm/cpu-features.rst
@@ -27,7 +27,7 @@ disabled, enables the optional AArch32 CPU feature, is only supported
 when using the KVM accelerator and when running on a host CPU type that
 supports the feature.  While ``aarch64`` currently only works with KVM,
 it could work with TCG.  CPU features that are specific to KVM are
-prefixed with "kvm-" and are described in "KVM VCPU Features".
+prefixed with "kvm-" and are described in "KVM vCPU Features".
 
 CPU Feature Probing
 ===================
@@ -167,22 +167,22 @@ disabling many SVE vector lengths would be quite verbose, the ``sve<N>`` CPU
 properties have special semantics (see "SVE CPU Property Parsing
 Semantics").
 
-KVM VCPU Features
+KVM vCPU Features
 =================
 
-KVM VCPU features are CPU features that are specific to KVM, such as
+KVM vCPU features are CPU features that are specific to KVM, such as
 paravirt features or features that enable CPU virtualization extensions.
 The features' CPU properties are only available when KVM is enabled and
-are named with the prefix "kvm-".  KVM VCPU features may be probed,
+are named with the prefix "kvm-".  KVM vCPU features may be probed,
 enabled, and disabled in the same way as other CPU features.  Below is
-the list of KVM VCPU features and their descriptions.
+the list of KVM vCPU features and their descriptions.
 
 ``kvm-no-adjvtime``
   By default kvm-no-adjvtime is disabled.  This means that by default
   the virtual time adjustment is enabled (vtime is not *not* adjusted).
 
   When virtual time adjustment is enabled each time the VM transitions
-  back to running state the VCPU's virtual counter is updated to
+  back to running state the vCPU's virtual counter is updated to
   ensure stopped time is not counted.  This avoids time jumps
   surprising guest OSes and applications, as long as they use the
   virtual counter for timekeeping.  However it has the side effect of
@@ -200,15 +200,15 @@ the list of KVM VCPU features and their descriptions.
 
   When kvm-steal-time is enabled a 64-bit guest can account for time
   its CPUs were not running due to the host not scheduling the
-  corresponding VCPU threads.  The accounting statistics may influence
+  corresponding vCPU threads.  The accounting statistics may influence
   the guest scheduler behavior and/or be exposed to the guest
   userspace.
 
-TCG VCPU Features
+TCG vCPU Features
 =================
 
-TCG VCPU features are CPU features that are specific to TCG.
-Below is the list of TCG VCPU features and their descriptions.
+TCG vCPU features are CPU features that are specific to TCG.
+Below is the list of TCG vCPU features and their descriptions.
 
 ``pauth``
   Enable or disable ``FEAT_Pauth`` entirely.
-- 
2.48.1

[PATCH 2/2] docs/cpu-features: Update "PAuth" (Pointer Authentication) details

[Kashyap Chamarthy]

PAuth (Pointer Authentication), a security feature in software, is
relevant for both KVM and QEMU.  Relect this fact into the docs:

  - For KVM, `pauth` is a binary, "on" vs "off" option.  The host CPU
    will choose the cryptographic algorithm.

  - For TCG, however, along with `pauth`, a couple of properties can be
    controlled -- they're are related to cryptographic algorithm choice.

Thanks to Peter Maydell and Marc Zyngier for explaining more about PAuth
on IRC (#qemu, OFTC).

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/system/arm/cpu-features.rst | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/docs/system/arm/cpu-features.rst b/docs/system/arm/cpu-features.rst
index 78f18c87a81..7f99f7614b4 100644
--- a/docs/system/arm/cpu-features.rst
+++ b/docs/system/arm/cpu-features.rst
@@ -204,11 +204,26 @@ the list of KVM vCPU features and their descriptions.
   the guest scheduler behavior and/or be exposed to the guest
   userspace.
 
-TCG vCPU Features
-=================
+"PAuth" (Pointer Authentication)
+================================
+
+PAuth (Pointer Authentication) is a security feature in software that
+was introduced in Armv8.3-A and Armv9.0-A.  It aims to protect against
+ROP (return-oriented programming) attacks.
+
+KVM
+---
+
+``pauth``
+
+  Enable or disable ``FEAT_Pauth``.  The host silicon will choose the
+  cryptographic algorithm.  No other properties can be controlled.
+
+TCG
+---
 
-TCG vCPU features are CPU features that are specific to TCG.
-Below is the list of TCG vCPU features and their descriptions.
+For TCG, along with ``pauth``, it is possible to control a few other
+properties of PAuth:
 
 ``pauth``
   Enable or disable ``FEAT_Pauth`` entirely.
-- 
2.48.1

Re: [PATCH 2/2] docs/cpu-features: Update "PAuth" (Pointer Authentication) details

[Marc Zyngier]

On Fri, 17 Jan 2025 19:11:06 +0000,
Kashyap Chamarthy <kchamart@redhat.com> wrote:
> 
> PAuth (Pointer Authentication), a security feature in software, is
> relevant for both KVM and QEMU.  Relect this fact into the docs:
> 
>   - For KVM, `pauth` is a binary, "on" vs "off" option.  The host CPU
>     will choose the cryptographic algorithm.
> 
>   - For TCG, however, along with `pauth`, a couple of properties can be
>     controlled -- they're are related to cryptographic algorithm choice.
> 
> Thanks to Peter Maydell and Marc Zyngier for explaining more about PAuth
> on IRC (#qemu, OFTC).
> 
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
>  docs/system/arm/cpu-features.rst | 23 +++++++++++++++++++----
>  1 file changed, 19 insertions(+), 4 deletions(-)
> 
> diff --git a/docs/system/arm/cpu-features.rst b/docs/system/arm/cpu-features.rst
> index 78f18c87a81..7f99f7614b4 100644
> --- a/docs/system/arm/cpu-features.rst
> +++ b/docs/system/arm/cpu-features.rst
> @@ -204,11 +204,26 @@ the list of KVM vCPU features and their descriptions.
>    the guest scheduler behavior and/or be exposed to the guest
>    userspace.
>  
> -TCG vCPU Features
> -=================
> +"PAuth" (Pointer Authentication)
> +================================
> +
> +PAuth (Pointer Authentication) is a security feature in software that
> +was introduced in Armv8.3-A and Armv9.0-A.  It aims to protect against

nit: given that ARMv9.0 is congruent to ARMv8.5 and therefore has all
the ARMv8.5 features, mentioning ARMv8.3 should be enough (but I don't
feel strongly about this). I feel much strongly about the use of
capital letters, but I live in a distant past... ;-)

> +ROP (return-oriented programming) attacks.
> +
> +KVM
> +---
> +
> +``pauth``
> +
> +  Enable or disable ``FEAT_Pauth``.  The host silicon will choose the
> +  cryptographic algorithm.  No other properties can be controlled.

nit: "choose" is a an odd choice of word. The host implementation
defines, or even imposes the signature algorithm, as well as the level
of PAuth support (PAuth, EPAC, PAuth2, FPAC, FPACCOMBINE, ...), some
of which are mutually exclusive (EPAC and PAuth2 are incompatible).

Maybe it would be worth capturing some of these details, as this has a
direct influence on the ability to migrate a VM.

Thanks,

	M.

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

Re: [PATCH 2/2] docs/cpu-features: Update "PAuth" (Pointer Authentication) details

[Kashyap Chamarthy]

On Sat, Jan 18, 2025 at 10:04:37AM +0000, Marc Zyngier wrote:
> On Fri, 17 Jan 2025 19:11:06 +0000,
> Kashyap Chamarthy <kchamart@redhat.com> wrote:
> > 
> > PAuth (Pointer Authentication), a security feature in software, is
> > relevant for both KVM and QEMU.  Relect this fact into the docs:
> > 
> >   - For KVM, `pauth` is a binary, "on" vs "off" option.  The host CPU
> >     will choose the cryptographic algorithm.
> > 
> >   - For TCG, however, along with `pauth`, a couple of properties can be
> >     controlled -- they're are related to cryptographic algorithm choice.
> > 
> > Thanks to Peter Maydell and Marc Zyngier for explaining more about PAuth
> > on IRC (#qemu, OFTC).
> > 
> > Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> > ---

[...]

> > -TCG vCPU Features
> > -=================
> > +"PAuth" (Pointer Authentication)
> > +================================
> > +
> > +PAuth (Pointer Authentication) is a security feature in software that
> > +was introduced in Armv8.3-A and Armv9.0-A.  It aims to protect against
> 
> nit: given that ARMv9.0 is congruent to ARMv8.5 and therefore has all
> the ARMv8.5 features, mentioning ARMv8.3 should be enough (but I don't
> feel strongly about this). I feel much strongly about the use of
> capital letters, but I live in a distant past... ;-)

Sure, I can keep it to just v8.3.

On capitalization, I don't feel strongly about it, I just followed this
commit[1], which explained that the rebranding changed "ARM" to "Arm":

    6fe6d6c9a95 (docs: Be consistent about capitalization of 'Arm',
    2020-03-09)

That's why I went with it.  I see you know this by your "distant past"
remark :)  To match the above, I'll keep the capitalization to "Arm".

> > +ROP (return-oriented programming) attacks.
> > +
> > +KVM
> > +---
> > +
> > +``pauth``
> > +
> > +  Enable or disable ``FEAT_Pauth``.  The host silicon will choose the
> > +  cryptographic algorithm.  No other properties can be controlled.
> 
> nit: "choose" is a an odd choice of word. The host implementation
> defines, or even imposes the signature algorithm, as well as the level
> of PAuth support (PAuth, EPAC, PAuth2, FPAC, FPACCOMBINE, ...), some
> of which are mutually exclusive (EPAC and PAuth2 are incompatible).
> 
> Maybe it would be worth capturing some of these details, as this has a
> direct influence on the ability to migrate a VM.

Yeah, I thought about it but I was not sure if it's the right place.  As
you point out, there's a live-migration impact depending on the level of
PAuth support, so mentioning these details will be useful.

I'll come up with something for v2.  Thanks for looking!

-- 
/kashyap

Re: [PATCH 1/2] docs/cpu-features: Consistently use vCPU instead of VCPU

[Peter Maydell]

On Fri, 17 Jan 2025 at 19:11, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
>  docs/system/arm/cpu-features.rst | 20 ++++++++++----------
>  1 file changed, 10 insertions(+), 10 deletions(-)
>

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH 2/2] docs/cpu-features: Update "PAuth" (Pointer Authentication) details

[Peter Maydell]

On Mon, 20 Jan 2025 at 09:06, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> On Sat, Jan 18, 2025 at 10:04:37AM +0000, Marc Zyngier wrote:
> > On Fri, 17 Jan 2025 19:11:06 +0000,
> > Kashyap Chamarthy <kchamart@redhat.com> wrote:
> > > +PAuth (Pointer Authentication) is a security feature in software that
> > > +was introduced in Armv8.3-A and Armv9.0-A.  It aims to protect against
> >
> > nit: given that ARMv9.0 is congruent to ARMv8.5 and therefore has all
> > the ARMv8.5 features, mentioning ARMv8.3 should be enough (but I don't
> > feel strongly about this). I feel much strongly about the use of
> > capital letters, but I live in a distant past... ;-)
>
> Sure, I can keep it to just v8.3.
>
> On capitalization, I don't feel strongly about it, I just followed this
> commit[1], which explained that the rebranding changed "ARM" to "Arm":
>
>     6fe6d6c9a95 (docs: Be consistent about capitalization of 'Arm',
>     2020-03-09)
>
> That's why I went with it.  I see you know this by your "distant past"
> remark :)  To match the above, I'll keep the capitalization to "Arm".

We should probably do another fix-capitalization pass on docs/,
because a bunch more "ARM" uses have crept in since 6fe6d6c9a95.
(6fe6d6c9a95's commit message says that architecture names like
"ARMv8" retain all-caps, but I think that was my personal taste
creeping in -- at any rate the current Arm ARM uses "Armv8",
"Armv9", etc. It was right that "ARM926" etc should stay all-caps,
though.)

thanks
-- PMM

Re: [PATCH 2/2] docs/cpu-features: Update "PAuth" (Pointer Authentication) details

[Kashyap Chamarthy]

On Mon, Jan 27, 2025 at 01:06:44PM +0000, Peter Maydell wrote:
> On Mon, 20 Jan 2025 at 09:06, Kashyap Chamarthy <kchamart@redhat.com> wrote:
> >
> > On Sat, Jan 18, 2025 at 10:04:37AM +0000, Marc Zyngier wrote:
> > > On Fri, 17 Jan 2025 19:11:06 +0000,
> > > Kashyap Chamarthy <kchamart@redhat.com> wrote:
> > > > +PAuth (Pointer Authentication) is a security feature in software that
> > > > +was introduced in Armv8.3-A and Armv9.0-A.  It aims to protect against
> > >
> > > nit: given that ARMv9.0 is congruent to ARMv8.5 and therefore has all
> > > the ARMv8.5 features, mentioning ARMv8.3 should be enough (but I don't
> > > feel strongly about this). I feel much strongly about the use of
> > > capital letters, but I live in a distant past... ;-)
> >
> > Sure, I can keep it to just v8.3.
> >
> > On capitalization, I don't feel strongly about it, I just followed this
> > commit[1], which explained that the rebranding changed "ARM" to "Arm":
> >
> >     6fe6d6c9a95 (docs: Be consistent about capitalization of 'Arm',
> >     2020-03-09)
> >
> > That's why I went with it.  I see you know this by your "distant past"
> > remark :)  To match the above, I'll keep the capitalization to "Arm".
> 
> We should probably do another fix-capitalization pass on docs/,
> because a bunch more "ARM" uses have crept in since 6fe6d6c9a95.

I can tack it to v2 of this.  I see about 22 occurrences in docs/:

    $> git grep "ARM " | wc -l
    22

> (6fe6d6c9a95's commit message says that architecture names like
> "ARMv8" retain all-caps, but I think that was my personal taste
> creeping in -- at any rate the current Arm ARM uses "Armv8",
> "Armv9", etc. It was right that "ARM926" etc should stay all-caps,
> though.)

Okay, so, architecture names should stick to "Armv8", etc.  (I too
would have preferred "ARMv8", but whatever the branding says.)

For all-caps: I assume you mean these should remain as-is: ARM926EJ-S,
ARM1176JZS, ARM1176, etc.

-- 
/kashyap

Re: [PATCH 2/2] docs/cpu-features: Update "PAuth" (Pointer Authentication) details

[Peter Maydell]

On Mon, 27 Jan 2025 at 13:35, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> On Mon, Jan 27, 2025 at 01:06:44PM +0000, Peter Maydell wrote:
> > We should probably do another fix-capitalization pass on docs/,
> > because a bunch more "ARM" uses have crept in since 6fe6d6c9a95.
>
> I can tack it to v2 of this.  I see about 22 occurrences in docs/:
>
>     $> git grep "ARM " | wc -l
>     22
>
> > (6fe6d6c9a95's commit message says that architecture names like
> > "ARMv8" retain all-caps, but I think that was my personal taste
> > creeping in -- at any rate the current Arm ARM uses "Armv8",
> > "Armv9", etc. It was right that "ARM926" etc should stay all-caps,
> > though.)
>
> Okay, so, architecture names should stick to "Armv8", etc.  (I too
> would have preferred "ARMv8", but whatever the branding says.)
>
> For all-caps: I assume you mean these should remain as-is: ARM926EJ-S,
> ARM1176JZS, ARM1176, etc.

Yes.

(We also have two instances of "ARM64" which isn't an Arm
official term at all and should maybe be "AArch64". If we
leave it as-is, I have no idea what capitalization to use
for it.)

thanks
-- PMM