[PATCH v2 0/3] docs: Small changes to system/arm/cpu-features and more

[PATCH v2 0/3] docs: Small changes to system/arm/cpu-features and more

[Kashyap Chamarthy]

[
    Resending v2, Peter pointed out that only patches 1 and 2 made it to
    the list; so I'm re-sending with a commit message touch-up:
    s/capitalization/capitaliaztion.

    Alex Bennée reviewed the first two patches that did show up:
    - https://lists.nongnu.org/archive/html/qemu-devel/2025-02/msg02838.html
    - https://lists.nongnu.org/archive/html/qemu-devel/2025-02/msg02837.html
]

In v2:

  - Add live-migration context to the PAuth docs (Marc Zyngier)

  - Fix the Arm capitlalization (Peter Maydell)
    (See:
    https://lists.gnu.org/archive/html/qemu-devel/2025-01/msg05137.html)

    * * *

v1 cover letter:

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 (3):
  docs/cpu-features: Consistently use vCPU instead of VCPU
  docs/cpu-features: Update "PAuth" (Pointer Authentication) details
  docs: Fix "Arm" capitalization

 docs/devel/testing/qgraph.rst        |  8 ++--
 docs/devel/vfio-iommufd.rst          |  2 +-
 docs/specs/fsi.rst                   |  2 +-
 docs/system/arm/aspeed.rst           |  6 +--
 docs/system/arm/b-l475e-iot01a.rst   |  2 +-
 docs/system/arm/cpu-features.rst     | 60 +++++++++++++++++++++++-----
 docs/system/arm/nrf.rst              |  4 +-
 docs/system/arm/nuvoton.rst          |  4 +-
 docs/system/arm/stm32.rst            | 12 +++---
 docs/system/arm/xlnx-versal-virt.rst | 12 +++---
 docs/system/arm/xlnx-zynq.rst        |  2 +-
 docs/system/guest-loader.rst         |  2 +-
 12 files changed, 77 insertions(+), 39 deletions(-)

-- 
2.48.1

[PATCH v2 1/3] 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 37d5dfd15b..a596316384 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

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

[Peter Maydell]

On Mon, 17 Feb 2025 at 16:38, 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 v2 1/3] docs/cpu-features: Consistently use vCPU instead of VCPU

[Eric Auger]

On 2/17/25 5:37 PM, Kashyap Chamarthy wrote:
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
Reviewed-by: Eric Auger <eric.auger@redhat.com>

Eric
> ---
>  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 37d5dfd15b..a596316384 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.

[PATCH v2 2/3] 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>
---
v2: address Marc Zyngier's comments:
    https://lists.gnu.org/archive/html/qemu-devel/2025-01/msg03451.html
---
 docs/system/arm/cpu-features.rst | 46 +++++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 4 deletions(-)

diff --git a/docs/system/arm/cpu-features.rst b/docs/system/arm/cpu-features.rst
index a596316384..94d260b573 100644
--- a/docs/system/arm/cpu-features.rst
+++ b/docs/system/arm/cpu-features.rst
@@ -204,11 +204,49 @@ 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.  It aims to protect against ROP
+(return-oriented programming) attacks.
+
+KVM
+---
+
+``pauth``
+
+  Enable or disable ``FEAT_Pauth``.  No other properties can be
+  controlled.
+
+  The host CPU will define the PAC (pointer authentication
+  code) cryptographic algorithm.
+
+  There are different "levels" of PAuth support.  The host CPU
+  definition will define that level (e.g. PAuth, EPAC, PAuth2, FPAC,
+  FPACCOMBINE, etc).  Refer to the Arm architecture extension documents
+  for details about the description of these features.
+
+Live migration and PAuth
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The level of PAuth support depends on which Arm architecture a given CPU
+supports (e.g. Armv8.3 vs. Armv8.6).  This gradation in PAuth support
+has implications for live migration.  For example, to be able to
+live-migrate from host-A (with Armv8.3) to host-B (with Arm v8.6):
+
+  - the source and destination hosts must "agree" on (a) the PAC
+    signature algorithm, and (b) all the sub-features of PAuth; or
+
+  - the alternative (and less desirable) option is to turn off PAuth
+    off on both source and destination — this is generally not
+    recommended, as PAuth is a security feature.
+
+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 v2 2/3] docs/cpu-features: Update "PAuth" (Pointer Authentication) details

[Eric Auger]

Hi Kashyap,


On 2/17/25 5:37 PM, Kashyap Chamarthy 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>
> ---
> v2: address Marc Zyngier's comments:
>     https://lists.gnu.org/archive/html/qemu-devel/2025-01/msg03451.html
> ---
>  docs/system/arm/cpu-features.rst | 46 +++++++++++++++++++++++++++++---
>  1 file changed, 42 insertions(+), 4 deletions(-)
>
> diff --git a/docs/system/arm/cpu-features.rst b/docs/system/arm/cpu-features.rst
> index a596316384..94d260b573 100644
> --- a/docs/system/arm/cpu-features.rst
> +++ b/docs/system/arm/cpu-features.rst
> @@ -204,11 +204,49 @@ 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.  It aims to protect against ROP
> +(return-oriented programming) attacks.
> +
> +KVM
> +---
> +
> +``pauth``
> +
> +  Enable or disable ``FEAT_Pauth``.  No other properties can be
> +  controlled.
> +
> +  The host CPU will define the PAC (pointer authentication
> +  code) cryptographic algorithm.
> +
> +  There are different "levels" of PAuth support.  The host CPU
> +  definition will define that level (e.g. PAuth, EPAC, PAuth2, FPAC,
> +  FPACCOMBINE, etc).  Refer to the Arm architecture extension documents
> +  for details about the description of these features.
> +
> +Live migration and PAuth
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The level of PAuth support depends on which Arm architecture a given CPU
> +supports (e.g. Armv8.3 vs. Armv8.6).  This gradation in PAuth support
> +has implications for live migration.  For example, to be able to
> +live-migrate from host-A (with Armv8.3) to host-B (with Arm v8.6):
> +
> +  - the source and destination hosts must "agree" on (a) the PAC
> +    signature algorithm, and (b) all the sub-features of PAuth; or
> +
> +  - the alternative (and less desirable) option is to turn off PAuth
> +    off on both source and destination — this is generally not
> +    recommended, as PAuth is a security feature.
> +
> +TCG
> +---
>  
> -TCG vCPU features are CPU features that are specific to TCG.
> -Below is the list of TCG vCPU features and their descriptions.

The resulting header layout seems weird to me.
Initially we had at top level (assuming ===):

KVM vCPU Features
TCG vCPU Features
SVE CPU Properties
SME CPU Properties
RME CPU Properties

and now

TCG vCPU Features has somehow disappeared giving the impression that
there are none.

SME and RME and TCG only if am not wrong while PAUTH and SVE are both
KVM and TCG

Maybe we shall
- rename KVM vCPU Features -> KVM only vCPU Features
- Add a TCG only vCPU features including both SME and RME ones
- introduce a top level KVM and TCG vCPU features with below:
PAUTH, SVE, detailing potential different semantic for both KVM and TCG mode

Also while we are at it, we may use vCPU everywhere instead of CPU (SVE
CPU Properties) and just skip CPU if it lays within the KVM and TCG vCPU
Features

Thanks

Eric




> +For TCG, along with ``pauth``, it is possible to control a few other
> +properties of PAuth:
>  
>  ``pauth``
>    Enable or disable ``FEAT_Pauth`` entirely.

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

[Kashyap Chamarthy]

(Cc: Richard Henderson; context: "SME" and "RME" feature discussion
below.)

On Mon, Feb 17, 2025 at 06:43:01PM +0100, Eric Auger wrote:
> Hi Kashyap,

Hey,

> 
> On 2/17/25 5:37 PM, Kashyap Chamarthy wrote:

[...]

> > Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> > ---
> > v2: address Marc Zyngier's comments:
> >     https://lists.gnu.org/archive/html/qemu-devel/2025-01/msg03451.html
> > ---

[...]

> > +Live migration and PAuth
> > +~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +The level of PAuth support depends on which Arm architecture a given CPU
> > +supports (e.g. Armv8.3 vs. Armv8.6).  This gradation in PAuth support
> > +has implications for live migration.  For example, to be able to
> > +live-migrate from host-A (with Armv8.3) to host-B (with Arm v8.6):
> > +
> > +  - the source and destination hosts must "agree" on (a) the PAC
> > +    signature algorithm, and (b) all the sub-features of PAuth; or
> > +
> > +  - the alternative (and less desirable) option is to turn off PAuth
> > +    off on both source and destination — this is generally not
> > +    recommended, as PAuth is a security feature.
> > +
> > +TCG
> > +---
> >  
> > -TCG vCPU features are CPU features that are specific to TCG.
> > -Below is the list of TCG vCPU features and their descriptions.
> 
> The resulting header layout seems weird to me.
> Initially we had at top level (assuming ===):
> 
> KVM vCPU Features
> TCG vCPU Features
> SVE CPU Properties
> SME CPU Properties
> RME CPU Properties
> 
> and now
> 
> TCG vCPU Features has somehow disappeared giving the impression that
> there are none.

I did think about it :) That's why I wrote this in the cover-letter; not
sure if you noticed it:

    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.

> SME and RME and TCG only if am not wrong while PAUTH and SVE are both
> KVM and TCG

I didn't know that.  I read the docs a bit more closer about SME, RME,
and SVE, and did some quick `git-annotate` analysis:

  - "SME is not supported by KVM at this time" — this was added in
    commit e74c097638 (target/arm: Add cpu properties for SME,
    2022-06-20).

    If it is still accurate, then yes, SME looks to be TCG-only.

  - "The status of RME support with QEMU is experimental" — this was
    added in commit 57223a4c24 (docs/system/arm: Document FEAT_RME,
    2023-06-22).

    The phrase "with QEMU" doesn't quite decisively tell me whether it
    is experimental for TCG-only, or if it also applies for KVM.  Maybe
    Richard (in Cc) can tell us more.

  - SVE seems to be for both KVM and TCG, as the section "SVE CPU
    Property Dependencies and Constraints" talks about KVM.

  - PAuth is both KVM and TCG.

> Maybe we shall
> - rename KVM vCPU Features -> KVM only vCPU Features
> - Add a TCG only vCPU features including both SME and RME ones
> - introduce a top level KVM and TCG vCPU features with below:
> PAUTH, SVE, detailing potential different semantic for both KVM and TCG mode

Yeah, it can be done.  Would you be okay if I do it as a follow-up?  As
this a re-work of the entire doc with several features.

> Also while we are at it, we may use vCPU everywhere instead of CPU (SVE
> CPU Properties) and just skip CPU if it lays within the KVM and TCG vCPU
> Features

Yes, make sense.

[...]

-- 
/kashyap

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

[Peter Maydell]

On Tue, 18 Feb 2025 at 11:29, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> (Cc: Richard Henderson; context: "SME" and "RME" feature discussion
> below.)
>
> On Mon, Feb 17, 2025 at 06:43:01PM +0100, Eric Auger wrote:
> > The resulting header layout seems weird to me.
> > Initially we had at top level (assuming ===):
> >
> > KVM vCPU Features
> > TCG vCPU Features
> > SVE CPU Properties
> > SME CPU Properties
> > RME CPU Properties
> >
> > and now
> >
> > TCG vCPU Features has somehow disappeared giving the impression that
> > there are none.

> > Maybe we shall
> > - rename KVM vCPU Features -> KVM only vCPU Features
> > - Add a TCG only vCPU features including both SME and RME ones
> > - introduce a top level KVM and TCG vCPU features with below:
> > PAUTH, SVE, detailing potential different semantic for both KVM and TCG mode
>
> Yeah, it can be done.  Would you be okay if I do it as a follow-up?  As
> this a re-work of the entire doc with several features.

I think personally I would favour not having the split of
"KVM only", "TCG only", etc sections. Instead document
all of the properties in the same format, and have each
property say whether it is TCG-specific, KVM-specific, etc.

Some of these properties may at some point in the future
change, after all -- SME is currently TCG only but may get
support in KVM and HVF in future; "aarch64" is currently
KVM only but we might some day support it in TCG.

thanks
-- PMM

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

[Eric Auger]

Hi,


On 2/18/25 12:34 PM, Peter Maydell wrote:
> On Tue, 18 Feb 2025 at 11:29, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>> (Cc: Richard Henderson; context: "SME" and "RME" feature discussion
>> below.)
>>
>> On Mon, Feb 17, 2025 at 06:43:01PM +0100, Eric Auger wrote:
>>> The resulting header layout seems weird to me.
>>> Initially we had at top level (assuming ===):
>>>
>>> KVM vCPU Features
>>> TCG vCPU Features
>>> SVE CPU Properties
>>> SME CPU Properties
>>> RME CPU Properties
>>>
>>> and now
>>>
>>> TCG vCPU Features has somehow disappeared giving the impression that
>>> there are none.
>>> Maybe we shall
>>> - rename KVM vCPU Features -> KVM only vCPU Features
>>> - Add a TCG only vCPU features including both SME and RME ones
>>> - introduce a top level KVM and TCG vCPU features with below:
>>> PAUTH, SVE, detailing potential different semantic for both KVM and TCG mode
>> Yeah, it can be done.  Would you be okay if I do it as a follow-up?  As
>> this a re-work of the entire doc with several features.
> I think personally I would favour not having the split of
> "KVM only", "TCG only", etc sections. Instead document
> all of the properties in the same format, and have each
> property say whether it is TCG-specific, KVM-specific, etc.
This other alternative looks totally fine to me as well.
>
> Some of these properties may at some point in the future
> change, after all -- SME is currently TCG only but may get
> support in KVM and HVF in future; "aarch64" is currently
> KVM only but we might some day support it in TCG.
agreed

Eric
>
> thanks
> -- PMM
>

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

[Kashyap Chamarthy]

On Tue, Feb 18, 2025 at 11:34:38AM +0000, Peter Maydell wrote:
> On Tue, 18 Feb 2025 at 11:29, Kashyap Chamarthy <kchamart@redhat.com> wrote:

[...]

> > > Maybe we shall
> > > - rename KVM vCPU Features -> KVM only vCPU Features
> > > - Add a TCG only vCPU features including both SME and RME ones
> > > - introduce a top level KVM and TCG vCPU features with below:
> > > PAUTH, SVE, detailing potential different semantic for both KVM and TCG mode
> >
> > Yeah, it can be done.  Would you be okay if I do it as a follow-up?  As
> > this a re-work of the entire doc with several features.
> 
> I think personally I would favour not having the split of
> "KVM only", "TCG only", etc sections. Instead document
> all of the properties in the same format, and have each
> property say whether it is TCG-specific, KVM-specific, etc.
> 
> Some of these properties may at some point in the future
> change, after all -- SME is currently TCG only but may get
> support in KVM and HVF in future; "aarch64" is currently
> KVM only but we might some day support it in TCG.

I agree.  As the PAuth case demonstrated, it only makes sense to
entirely do away with KVM- and TCG-specific sections and use a
consistent format througout.  That way, no need to remember to update
outdated sections.  It's also consistent with the x86 docs[1], where we
don't draw attention to KVM- or TCG-specific features.

I can rework the doc and send a follow-up.  (Eric: I assume you're also
fine with Peter's suggestion above :))

[1] https://www.qemu.org/docs/master/system/i386/cpu.html

-- 
/kashyap

[PATCH v2 3/3] docs: Fix "Arm" capitalization

[Kashyap Chamarthy]

This is based on Peter's suggestion here[1].

I simply addrressed the occurrences that I found with `git grep "ARM "`
in the docs/ directory.  I didn't touch stuff like these "StrongARM",
ARM926EJ-S, ARM1176JZS, etc.  Related commit[2].

[1] https://lists.gnu.org/archive/html/qemu-devel/2025-01/msg05137.html
    - docs/cpu-features: Update "PAuth" (Pointer Authentication) details

[2] 6fe6d6c9a9 (docs: Be consistent about capitalization of 'Arm',
    2020-03-09)

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/devel/testing/qgraph.rst        |  8 ++++----
 docs/devel/vfio-iommufd.rst          |  2 +-
 docs/specs/fsi.rst                   |  2 +-
 docs/system/arm/aspeed.rst           |  6 +++---
 docs/system/arm/b-l475e-iot01a.rst   |  2 +-
 docs/system/arm/nrf.rst              |  4 ++--
 docs/system/arm/nuvoton.rst          |  4 ++--
 docs/system/arm/stm32.rst            | 12 ++++++------
 docs/system/arm/xlnx-versal-virt.rst | 12 ++++++------
 docs/system/arm/xlnx-zynq.rst        |  2 +-
 docs/system/guest-loader.rst         |  2 +-
 11 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/docs/devel/testing/qgraph.rst b/docs/devel/testing/qgraph.rst
index 43342d9d65..30ff055fae 100644
--- a/docs/devel/testing/qgraph.rst
+++ b/docs/devel/testing/qgraph.rst
@@ -8,7 +8,7 @@ take care of booting QEMU with the right machine and devices.
 This makes each test "hardcoded" for a specific configuration, reducing
 the possible coverage that it can reach.
 
-For example, the sdhci device is supported on both x86_64 and ARM boards,
+For example, the sdhci device is supported on both x86_64 and Arm boards,
 therefore a generic sdhci test should test all machines and drivers that
 support that device.
 Using only libqos APIs, the test has to manually take care of
@@ -195,7 +195,7 @@ there.
 The ``arm/raspi2b`` machine node is listed as "UNAVAILABLE". Although it is
 reachable from the root via '' -> 'arm/raspi2b' the node is unavailable because
 the QEMU binary did not list it when queried by the framework. This is expected
-because we used the ``qemu-system-x86_64`` binary which does not support ARM
+because we used the ``qemu-system-x86_64`` binary which does not support Arm
 machine types.
 
 If a test is unexpectedly listed as "UNAVAILABLE", first check that the "ALL
@@ -214,9 +214,9 @@ Here we continue the ``sdhci`` use case, with the following scenario:
 
 - ``sdhci-test`` aims to test the ``read[q,w], writeq`` functions
   offered by the ``sdhci`` drivers.
-- The current ``sdhci`` device is supported by both ``x86_64/pc`` and ``ARM``
+- The current ``sdhci`` device is supported by both ``x86_64/pc`` and ``Arm``
   (in this example we focus on the ``arm-raspi2b``) machines.
-- QEMU offers 2 types of drivers: ``QSDHCI_MemoryMapped`` for ``ARM`` and
+- QEMU offers 2 types of drivers: ``QSDHCI_MemoryMapped`` for ``Arm`` and
   ``QSDHCI_PCI`` for ``x86_64/pc``. Both implement the
   ``read[q,w], writeq`` functions.
 
diff --git a/docs/devel/vfio-iommufd.rst b/docs/devel/vfio-iommufd.rst
index 3d1c11f175..fe8a7365e3 100644
--- a/docs/devel/vfio-iommufd.rst
+++ b/docs/devel/vfio-iommufd.rst
@@ -122,7 +122,7 @@ container:
 Supported platform
 ==================
 
-Supports x86, ARM and s390x currently.
+Supports x86, Arm, and s390x currently.
 
 Caveats
 =======
diff --git a/docs/specs/fsi.rst b/docs/specs/fsi.rst
index af87822531..f7d86d3e37 100644
--- a/docs/specs/fsi.rst
+++ b/docs/specs/fsi.rst
@@ -40,7 +40,7 @@ for the implementation are: (see the `FSI specification`_ for more details)
    MMIO-mapping of the CFAM address straight onto a sub-region of the OPB
    address space.
 
-5. An APB-to-OPB bridge enabling access to the OPB from the ARM core in the
+5. An APB-to-OPB bridge enabling access to the OPB from the Arm core in the
    AST2600. Hardware limitations prevent the OPB from being directly mapped
    into APB, so all accesses are indirect through the bridge.
 
diff --git a/docs/system/arm/aspeed.rst b/docs/system/arm/aspeed.rst
index fa4aa28eef..42096fb941 100644
--- a/docs/system/arm/aspeed.rst
+++ b/docs/system/arm/aspeed.rst
@@ -5,8 +5,8 @@ The QEMU Aspeed machines model BMCs of various OpenPOWER systems and
 Aspeed evaluation boards. They are based on different releases of the
 Aspeed SoC : the AST2400 integrating an ARM926EJ-S CPU (400MHz), the
 AST2500 with an ARM1176JZS CPU (800MHz), the AST2600
-with dual cores ARM Cortex-A7 CPUs (1.2GHz) and more recently the AST2700
-with quad cores ARM Cortex-A35 64 bits CPUs (1.6GHz)
+with dual cores Arm Cortex-A7 CPUs (1.2GHz) and more recently the AST2700
+with quad cores Arm Cortex-A35 64 bits CPUs (1.6GHz)
 
 The SoC comes with RAM, Gigabit ethernet, USB, SD/MMC, USB, SPI, I2C,
 etc.
@@ -275,7 +275,7 @@ Aspeed minibmc family boards (``ast1030-evb``)
 
 The QEMU Aspeed machines model mini BMCs of various Aspeed evaluation
 boards. They are based on different releases of the
-Aspeed SoC : the AST1030 integrating an ARM Cortex M4F CPU (200MHz).
+Aspeed SoC : the AST1030 integrating an Arm Cortex M4F CPU (200MHz).
 
 The SoC comes with SRAM, SPI, I2C, etc.
 
diff --git a/docs/system/arm/b-l475e-iot01a.rst b/docs/system/arm/b-l475e-iot01a.rst
index 2adcc4b4c1..7f891719d5 100644
--- a/docs/system/arm/b-l475e-iot01a.rst
+++ b/docs/system/arm/b-l475e-iot01a.rst
@@ -2,7 +2,7 @@ B-L475E-IOT01A IoT Node (``b-l475e-iot01a``)
 ============================================
 
 The B-L475E-IOT01A IoT Node uses the STM32L475VG SoC which is based on
-ARM Cortex-M4F core. It is part of STMicroelectronics
+Arm Cortex-M4F core. It is part of STMicroelectronics
 :doc:`STM32 boards </system/arm/stm32>` and more specifically the STM32L4
 ultra-low power series. The STM32L4x5 chip runs at up to 80 MHz and
 integrates 128 KiB of SRAM and up to 1MiB of Flash. The B-L475E-IOT01A board
diff --git a/docs/system/arm/nrf.rst b/docs/system/arm/nrf.rst
index eda87bd760..e0ea6a8b7e 100644
--- a/docs/system/arm/nrf.rst
+++ b/docs/system/arm/nrf.rst
@@ -1,7 +1,7 @@
 Nordic nRF boards (``microbit``)
 ================================
 
-The `Nordic nRF`_ chips are a family of ARM-based System-on-Chip that
+The `Nordic nRF`_ chips are a family of Arm-based System-on-Chip that
 are designed to be used for low-power and short-range wireless solutions.
 
 .. _Nordic nRF: https://www.nordicsemi.com/Products
@@ -18,7 +18,7 @@ supported by QEMU.
 Supported devices
 -----------------
 
- * ARM Cortex-M0 (ARMv6-M)
+ * Arm Cortex-M0 (ARMv6-M)
  * Serial ports (UART)
  * Clock controller
  * Timers
diff --git a/docs/system/arm/nuvoton.rst b/docs/system/arm/nuvoton.rst
index 05059378e5..e0da2297ff 100644
--- a/docs/system/arm/nuvoton.rst
+++ b/docs/system/arm/nuvoton.rst
@@ -1,9 +1,9 @@
 Nuvoton iBMC boards (``kudo-bmc``, ``mori-bmc``, ``npcm750-evb``, ``quanta-gbs-bmc``, ``quanta-gsj``)
 =====================================================================================================
 
-The `Nuvoton iBMC`_ chips (NPCM7xx) are a family of ARM-based SoCs that are
+The `Nuvoton iBMC`_ chips (NPCM7xx) are a family of Arm-based SoCs that are
 designed to be used as Baseboard Management Controllers (BMCs) in various
-servers. They all feature one or two ARM Cortex-A9 CPU cores, as well as an
+servers. They all feature one or two Arm Cortex-A9 CPU cores, as well as an
 assortment of peripherals targeted for either Enterprise or Data Center /
 Hyperscale applications. The former is a superset of the latter, so NPCM750 has
 all the peripherals of NPCM730 and more.
diff --git a/docs/system/arm/stm32.rst b/docs/system/arm/stm32.rst
index 511e3eb9ac..381d2c4386 100644
--- a/docs/system/arm/stm32.rst
+++ b/docs/system/arm/stm32.rst
@@ -1,24 +1,24 @@
 STMicroelectronics STM32 boards (``netduino2``, ``netduinoplus2``, ``olimex-stm32-h405``, ``stm32vldiscovery``)
 ===============================================================================================================
 
-The `STM32`_ chips are a family of 32-bit ARM-based microcontroller by
+The `STM32`_ chips are a family of 32-bit Arm-based microcontroller by
 STMicroelectronics.
 
 .. _STM32: https://www.st.com/en/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus.html
 
-The STM32F1 series is based on ARM Cortex-M3 core. The following machines are
+The STM32F1 series is based on Arm Cortex-M3 core. The following machines are
 based on this chip :
 
 - ``stm32vldiscovery``  STM32VLDISCOVERY board with STM32F100RBT6 microcontroller
 
-The STM32F2 series is based on ARM Cortex-M3 core. The following machines are
+The STM32F2 series is based on Arm Cortex-M3 core. The following machines are
 based on this chip :
 
 - ``netduino2``         Netduino 2 board with STM32F205RFT6 microcontroller
 
-The STM32F4 series is based on ARM Cortex-M4F core, as well as the STM32L4
+The STM32F4 series is based on Arm Cortex-M4F core, as well as the STM32L4
 ultra-low-power series. The STM32F4 series is pin-to-pin compatible with STM32F2 series.
-The following machines are based on this ARM Cortex-M4F chip :
+The following machines are based on this Arm Cortex-M4F chip :
 
 - ``netduinoplus2``     Netduino Plus 2 board with STM32F405RGT6 microcontroller
 - ``olimex-stm32-h405`` Olimex STM32 H405 board with STM32F405RGT6 microcontroller
@@ -29,7 +29,7 @@ There are many other STM32 series that are currently not supported by QEMU.
 Supported devices
 -----------------
 
- * ARM Cortex-M3, Cortex M4F
+ * Arm Cortex-M3, Cortex M4F
  * Analog to Digital Converter (ADC)
  * EXTI interrupt
  * Serial ports (USART)
diff --git a/docs/system/arm/xlnx-versal-virt.rst b/docs/system/arm/xlnx-versal-virt.rst
index c5f35f28e4..1b3a0ad6a5 100644
--- a/docs/system/arm/xlnx-versal-virt.rst
+++ b/docs/system/arm/xlnx-versal-virt.rst
@@ -19,12 +19,12 @@ limitations. Currently, we support the following cores and devices:
 
 Implemented CPU cores:
 
-- 2 ACPUs (ARM Cortex-A72)
+- 2 ACPUs (Arm Cortex-A72)
 
 Implemented devices:
 
-- Interrupt controller (ARM GICv3)
-- 2 UARTs (ARM PL011)
+- Interrupt controller (Arm GICv3)
+- 2 UARTs (Arm PL011)
 - An RTC (Versal built-in)
 - 2 GEMs (Cadence MACB Ethernet MACs)
 - 8 ADMA (Xilinx zDMA) channels
@@ -70,7 +70,7 @@ provides EL3 firmware to handle PSCI.
 
 A few examples:
 
-Direct Linux boot of a generic ARM64 upstream Linux kernel:
+Direct Linux boot of a generic Arm64 upstream Linux kernel:
 
 .. code-block:: bash
 
@@ -95,7 +95,7 @@ Direct Linux boot of PetaLinux 2019.2:
       -device virtio-rng-device,bus=virtio-mmio-bus.0,rng=rng0 \
       -object rng-random,filename=/dev/urandom,id=rng0
 
-Boot PetaLinux 2019.2 via ARM Trusted Firmware (2018.3 because the 2019.2
+Boot PetaLinux 2019.2 via Arm Trusted Firmware (2018.3 because the 2019.2
 version of ATF tries to configure the CCI which we don't model) and U-boot:
 
 .. code-block:: bash
@@ -149,7 +149,7 @@ Run the following at the U-Boot prompt:
   fdt set /chosen/dom0 reg <0x00000000 0x40000000 0x0 0x03100000>
   booti 30000000 - 20000000
 
-Boot Linux as Dom0 on Xen via ARM Trusted Firmware and U-Boot:
+Boot Linux as Dom0 on Xen via Arm Trusted Firmware and U-Boot:
 
 .. code-block:: bash
 
diff --git a/docs/system/arm/xlnx-zynq.rst b/docs/system/arm/xlnx-zynq.rst
index ade18a3fe1..94eedf0e81 100644
--- a/docs/system/arm/xlnx-zynq.rst
+++ b/docs/system/arm/xlnx-zynq.rst
@@ -29,7 +29,7 @@ QEMU xilinx-zynq-a9 board supports following devices:
 
 Running
 """""""
-Direct Linux boot of a generic ARM upstream Linux kernel:
+Direct Linux boot of a generic Arm upstream Linux kernel:
 
 .. code-block:: bash
 
diff --git a/docs/system/guest-loader.rst b/docs/system/guest-loader.rst
index 304ee5d531..12436cc791 100644
--- a/docs/system/guest-loader.rst
+++ b/docs/system/guest-loader.rst
@@ -32,7 +32,7 @@ size. Additional information can be passed with by using additional
 arguments.
 
 Currently the only supported machines which use FDT data to boot are
-the ARM and RiscV ``virt`` machines.
+the Arm and RiscV ``virt`` machines.
 
 Arguments
 ^^^^^^^^^
-- 
2.48.1

Re: [PATCH v2 3/3] docs: Fix "Arm" capitalization

[Peter Maydell]

On Mon, 17 Feb 2025 at 16:38, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> This is based on Peter's suggestion here[1].
>
> I simply addrressed the occurrences that I found with `git grep "ARM "`
> in the docs/ directory.  I didn't touch stuff like these "StrongARM",
> ARM926EJ-S, ARM1176JZS, etc.  Related commit[2].
>
> [1] https://lists.gnu.org/archive/html/qemu-devel/2025-01/msg05137.html
>     - docs/cpu-features: Update "PAuth" (Pointer Authentication) details
>
> [2] 6fe6d6c9a9 (docs: Be consistent about capitalization of 'Arm',
>     2020-03-09)
>
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---

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

thanks
-- PMM

Re: [PATCH v2 3/3] docs: Fix "Arm" capitalization

[Eric Auger]

Hi,

On 2/17/25 5:37 PM, Kashyap Chamarthy wrote:
> This is based on Peter's suggestion here[1].
>
> I simply addrressed the occurrences that I found with `git grep "ARM "`
adressed
> in the docs/ directory.  I didn't touch stuff like these "StrongARM",
> ARM926EJ-S, ARM1176JZS, etc.  Related commit[2].
>
> [1] https://lists.gnu.org/archive/html/qemu-devel/2025-01/msg05137.html
>     - docs/cpu-features: Update "PAuth" (Pointer Authentication) details
>
> [2] 6fe6d6c9a9 (docs: Be consistent about capitalization of 'Arm',
>     2020-03-09)
>
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
Reviewed-by: Eric Auger <eric.auger@redhat.com>

Eric
> ---
>  docs/devel/testing/qgraph.rst        |  8 ++++----
>  docs/devel/vfio-iommufd.rst          |  2 +-
>  docs/specs/fsi.rst                   |  2 +-
>  docs/system/arm/aspeed.rst           |  6 +++---
>  docs/system/arm/b-l475e-iot01a.rst   |  2 +-
>  docs/system/arm/nrf.rst              |  4 ++--
>  docs/system/arm/nuvoton.rst          |  4 ++--
>  docs/system/arm/stm32.rst            | 12 ++++++------
>  docs/system/arm/xlnx-versal-virt.rst | 12 ++++++------
>  docs/system/arm/xlnx-zynq.rst        |  2 +-
>  docs/system/guest-loader.rst         |  2 +-
>  11 files changed, 28 insertions(+), 28 deletions(-)
>
> diff --git a/docs/devel/testing/qgraph.rst b/docs/devel/testing/qgraph.rst
> index 43342d9d65..30ff055fae 100644
> --- a/docs/devel/testing/qgraph.rst
> +++ b/docs/devel/testing/qgraph.rst
> @@ -8,7 +8,7 @@ take care of booting QEMU with the right machine and devices.
>  This makes each test "hardcoded" for a specific configuration, reducing
>  the possible coverage that it can reach.
>  
> -For example, the sdhci device is supported on both x86_64 and ARM boards,
> +For example, the sdhci device is supported on both x86_64 and Arm boards,
>  therefore a generic sdhci test should test all machines and drivers that
>  support that device.
>  Using only libqos APIs, the test has to manually take care of
> @@ -195,7 +195,7 @@ there.
>  The ``arm/raspi2b`` machine node is listed as "UNAVAILABLE". Although it is
>  reachable from the root via '' -> 'arm/raspi2b' the node is unavailable because
>  the QEMU binary did not list it when queried by the framework. This is expected
> -because we used the ``qemu-system-x86_64`` binary which does not support ARM
> +because we used the ``qemu-system-x86_64`` binary which does not support Arm
>  machine types.
>  
>  If a test is unexpectedly listed as "UNAVAILABLE", first check that the "ALL
> @@ -214,9 +214,9 @@ Here we continue the ``sdhci`` use case, with the following scenario:
>  
>  - ``sdhci-test`` aims to test the ``read[q,w], writeq`` functions
>    offered by the ``sdhci`` drivers.
> -- The current ``sdhci`` device is supported by both ``x86_64/pc`` and ``ARM``
> +- The current ``sdhci`` device is supported by both ``x86_64/pc`` and ``Arm``
>    (in this example we focus on the ``arm-raspi2b``) machines.
> -- QEMU offers 2 types of drivers: ``QSDHCI_MemoryMapped`` for ``ARM`` and
> +- QEMU offers 2 types of drivers: ``QSDHCI_MemoryMapped`` for ``Arm`` and
>    ``QSDHCI_PCI`` for ``x86_64/pc``. Both implement the
>    ``read[q,w], writeq`` functions.
>  
> diff --git a/docs/devel/vfio-iommufd.rst b/docs/devel/vfio-iommufd.rst
> index 3d1c11f175..fe8a7365e3 100644
> --- a/docs/devel/vfio-iommufd.rst
> +++ b/docs/devel/vfio-iommufd.rst
> @@ -122,7 +122,7 @@ container:
>  Supported platform
>  ==================
>  
> -Supports x86, ARM and s390x currently.
> +Supports x86, Arm, and s390x currently.
>  
>  Caveats
>  =======
> diff --git a/docs/specs/fsi.rst b/docs/specs/fsi.rst
> index af87822531..f7d86d3e37 100644
> --- a/docs/specs/fsi.rst
> +++ b/docs/specs/fsi.rst
> @@ -40,7 +40,7 @@ for the implementation are: (see the `FSI specification`_ for more details)
>     MMIO-mapping of the CFAM address straight onto a sub-region of the OPB
>     address space.
>  
> -5. An APB-to-OPB bridge enabling access to the OPB from the ARM core in the
> +5. An APB-to-OPB bridge enabling access to the OPB from the Arm core in the
>     AST2600. Hardware limitations prevent the OPB from being directly mapped
>     into APB, so all accesses are indirect through the bridge.
>  
> diff --git a/docs/system/arm/aspeed.rst b/docs/system/arm/aspeed.rst
> index fa4aa28eef..42096fb941 100644
> --- a/docs/system/arm/aspeed.rst
> +++ b/docs/system/arm/aspeed.rst
> @@ -5,8 +5,8 @@ The QEMU Aspeed machines model BMCs of various OpenPOWER systems and
>  Aspeed evaluation boards. They are based on different releases of the
>  Aspeed SoC : the AST2400 integrating an ARM926EJ-S CPU (400MHz), the
>  AST2500 with an ARM1176JZS CPU (800MHz), the AST2600
> -with dual cores ARM Cortex-A7 CPUs (1.2GHz) and more recently the AST2700
> -with quad cores ARM Cortex-A35 64 bits CPUs (1.6GHz)
> +with dual cores Arm Cortex-A7 CPUs (1.2GHz) and more recently the AST2700
> +with quad cores Arm Cortex-A35 64 bits CPUs (1.6GHz)
>  
>  The SoC comes with RAM, Gigabit ethernet, USB, SD/MMC, USB, SPI, I2C,
>  etc.
> @@ -275,7 +275,7 @@ Aspeed minibmc family boards (``ast1030-evb``)
>  
>  The QEMU Aspeed machines model mini BMCs of various Aspeed evaluation
>  boards. They are based on different releases of the
> -Aspeed SoC : the AST1030 integrating an ARM Cortex M4F CPU (200MHz).
> +Aspeed SoC : the AST1030 integrating an Arm Cortex M4F CPU (200MHz).
>  
>  The SoC comes with SRAM, SPI, I2C, etc.
>  
> diff --git a/docs/system/arm/b-l475e-iot01a.rst b/docs/system/arm/b-l475e-iot01a.rst
> index 2adcc4b4c1..7f891719d5 100644
> --- a/docs/system/arm/b-l475e-iot01a.rst
> +++ b/docs/system/arm/b-l475e-iot01a.rst
> @@ -2,7 +2,7 @@ B-L475E-IOT01A IoT Node (``b-l475e-iot01a``)
>  ============================================
>  
>  The B-L475E-IOT01A IoT Node uses the STM32L475VG SoC which is based on
> -ARM Cortex-M4F core. It is part of STMicroelectronics
> +Arm Cortex-M4F core. It is part of STMicroelectronics
>  :doc:`STM32 boards </system/arm/stm32>` and more specifically the STM32L4
>  ultra-low power series. The STM32L4x5 chip runs at up to 80 MHz and
>  integrates 128 KiB of SRAM and up to 1MiB of Flash. The B-L475E-IOT01A board
> diff --git a/docs/system/arm/nrf.rst b/docs/system/arm/nrf.rst
> index eda87bd760..e0ea6a8b7e 100644
> --- a/docs/system/arm/nrf.rst
> +++ b/docs/system/arm/nrf.rst
> @@ -1,7 +1,7 @@
>  Nordic nRF boards (``microbit``)
>  ================================
>  
> -The `Nordic nRF`_ chips are a family of ARM-based System-on-Chip that
> +The `Nordic nRF`_ chips are a family of Arm-based System-on-Chip that
>  are designed to be used for low-power and short-range wireless solutions.
>  
>  .. _Nordic nRF: https://www.nordicsemi.com/Products
> @@ -18,7 +18,7 @@ supported by QEMU.
>  Supported devices
>  -----------------
>  
> - * ARM Cortex-M0 (ARMv6-M)
> + * Arm Cortex-M0 (ARMv6-M)
>   * Serial ports (UART)
>   * Clock controller
>   * Timers
> diff --git a/docs/system/arm/nuvoton.rst b/docs/system/arm/nuvoton.rst
> index 05059378e5..e0da2297ff 100644
> --- a/docs/system/arm/nuvoton.rst
> +++ b/docs/system/arm/nuvoton.rst
> @@ -1,9 +1,9 @@
>  Nuvoton iBMC boards (``kudo-bmc``, ``mori-bmc``, ``npcm750-evb``, ``quanta-gbs-bmc``, ``quanta-gsj``)
>  =====================================================================================================
>  
> -The `Nuvoton iBMC`_ chips (NPCM7xx) are a family of ARM-based SoCs that are
> +The `Nuvoton iBMC`_ chips (NPCM7xx) are a family of Arm-based SoCs that are
>  designed to be used as Baseboard Management Controllers (BMCs) in various
> -servers. They all feature one or two ARM Cortex-A9 CPU cores, as well as an
> +servers. They all feature one or two Arm Cortex-A9 CPU cores, as well as an
>  assortment of peripherals targeted for either Enterprise or Data Center /
>  Hyperscale applications. The former is a superset of the latter, so NPCM750 has
>  all the peripherals of NPCM730 and more.
> diff --git a/docs/system/arm/stm32.rst b/docs/system/arm/stm32.rst
> index 511e3eb9ac..381d2c4386 100644
> --- a/docs/system/arm/stm32.rst
> +++ b/docs/system/arm/stm32.rst
> @@ -1,24 +1,24 @@
>  STMicroelectronics STM32 boards (``netduino2``, ``netduinoplus2``, ``olimex-stm32-h405``, ``stm32vldiscovery``)
>  ===============================================================================================================
>  
> -The `STM32`_ chips are a family of 32-bit ARM-based microcontroller by
> +The `STM32`_ chips are a family of 32-bit Arm-based microcontroller by
>  STMicroelectronics.
>  
>  .. _STM32: https://www.st.com/en/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus.html
>  
> -The STM32F1 series is based on ARM Cortex-M3 core. The following machines are
> +The STM32F1 series is based on Arm Cortex-M3 core. The following machines are
>  based on this chip :
>  
>  - ``stm32vldiscovery``  STM32VLDISCOVERY board with STM32F100RBT6 microcontroller
>  
> -The STM32F2 series is based on ARM Cortex-M3 core. The following machines are
> +The STM32F2 series is based on Arm Cortex-M3 core. The following machines are
>  based on this chip :
>  
>  - ``netduino2``         Netduino 2 board with STM32F205RFT6 microcontroller
>  
> -The STM32F4 series is based on ARM Cortex-M4F core, as well as the STM32L4
> +The STM32F4 series is based on Arm Cortex-M4F core, as well as the STM32L4
>  ultra-low-power series. The STM32F4 series is pin-to-pin compatible with STM32F2 series.
> -The following machines are based on this ARM Cortex-M4F chip :
> +The following machines are based on this Arm Cortex-M4F chip :
>  
>  - ``netduinoplus2``     Netduino Plus 2 board with STM32F405RGT6 microcontroller
>  - ``olimex-stm32-h405`` Olimex STM32 H405 board with STM32F405RGT6 microcontroller
> @@ -29,7 +29,7 @@ There are many other STM32 series that are currently not supported by QEMU.
>  Supported devices
>  -----------------
>  
> - * ARM Cortex-M3, Cortex M4F
> + * Arm Cortex-M3, Cortex M4F
>   * Analog to Digital Converter (ADC)
>   * EXTI interrupt
>   * Serial ports (USART)
> diff --git a/docs/system/arm/xlnx-versal-virt.rst b/docs/system/arm/xlnx-versal-virt.rst
> index c5f35f28e4..1b3a0ad6a5 100644
> --- a/docs/system/arm/xlnx-versal-virt.rst
> +++ b/docs/system/arm/xlnx-versal-virt.rst
> @@ -19,12 +19,12 @@ limitations. Currently, we support the following cores and devices:
>  
>  Implemented CPU cores:
>  
> -- 2 ACPUs (ARM Cortex-A72)
> +- 2 ACPUs (Arm Cortex-A72)
>  
>  Implemented devices:
>  
> -- Interrupt controller (ARM GICv3)
> -- 2 UARTs (ARM PL011)
> +- Interrupt controller (Arm GICv3)
> +- 2 UARTs (Arm PL011)
>  - An RTC (Versal built-in)
>  - 2 GEMs (Cadence MACB Ethernet MACs)
>  - 8 ADMA (Xilinx zDMA) channels
> @@ -70,7 +70,7 @@ provides EL3 firmware to handle PSCI.
>  
>  A few examples:
>  
> -Direct Linux boot of a generic ARM64 upstream Linux kernel:
> +Direct Linux boot of a generic Arm64 upstream Linux kernel:
>  
>  .. code-block:: bash
>  
> @@ -95,7 +95,7 @@ Direct Linux boot of PetaLinux 2019.2:
>        -device virtio-rng-device,bus=virtio-mmio-bus.0,rng=rng0 \
>        -object rng-random,filename=/dev/urandom,id=rng0
>  
> -Boot PetaLinux 2019.2 via ARM Trusted Firmware (2018.3 because the 2019.2
> +Boot PetaLinux 2019.2 via Arm Trusted Firmware (2018.3 because the 2019.2
>  version of ATF tries to configure the CCI which we don't model) and U-boot:
>  
>  .. code-block:: bash
> @@ -149,7 +149,7 @@ Run the following at the U-Boot prompt:
>    fdt set /chosen/dom0 reg <0x00000000 0x40000000 0x0 0x03100000>
>    booti 30000000 - 20000000
>  
> -Boot Linux as Dom0 on Xen via ARM Trusted Firmware and U-Boot:
> +Boot Linux as Dom0 on Xen via Arm Trusted Firmware and U-Boot:
>  
>  .. code-block:: bash
>  
> diff --git a/docs/system/arm/xlnx-zynq.rst b/docs/system/arm/xlnx-zynq.rst
> index ade18a3fe1..94eedf0e81 100644
> --- a/docs/system/arm/xlnx-zynq.rst
> +++ b/docs/system/arm/xlnx-zynq.rst
> @@ -29,7 +29,7 @@ QEMU xilinx-zynq-a9 board supports following devices:
>  
>  Running
>  """""""
> -Direct Linux boot of a generic ARM upstream Linux kernel:
> +Direct Linux boot of a generic Arm upstream Linux kernel:
>  
>  .. code-block:: bash
>  
> diff --git a/docs/system/guest-loader.rst b/docs/system/guest-loader.rst
> index 304ee5d531..12436cc791 100644
> --- a/docs/system/guest-loader.rst
> +++ b/docs/system/guest-loader.rst
> @@ -32,7 +32,7 @@ size. Additional information can be passed with by using additional
>  arguments.
>  
>  Currently the only supported machines which use FDT data to boot are
> -the ARM and RiscV ``virt`` machines.
> +the Arm and RiscV ``virt`` machines.
>  
>  Arguments
>  ^^^^^^^^^

[PATCH v2 0/3] docs: Small changes to system/arm/cpu-features and more

[Kashyap Chamarthy]

In v2:

  - Add live-migration context to the PAuth docs (Marc Zyngier)

  - Fix the Arm capitlalization (Peter Maydell)
    (See:
    https://lists.gnu.org/archive/html/qemu-devel/2025-01/msg05137.html)

    * * *

v1 cover letter:

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 (3):
  docs/cpu-features: Consistently use vCPU instead of VCPU
  docs/cpu-features: Update "PAuth" (Pointer Authentication) details
  docs: Fix "Arm" capitaliaztion

 docs/devel/testing/qgraph.rst        |  8 ++--
 docs/devel/vfio-iommufd.rst          |  2 +-
 docs/specs/fsi.rst                   |  2 +-
 docs/system/arm/aspeed.rst           |  6 +--
 docs/system/arm/b-l475e-iot01a.rst   |  2 +-
 docs/system/arm/cpu-features.rst     | 60 +++++++++++++++++++++++-----
 docs/system/arm/nrf.rst              |  4 +-
 docs/system/arm/nuvoton.rst          |  4 +-
 docs/system/arm/stm32.rst            | 12 +++---
 docs/system/arm/xlnx-versal-virt.rst | 12 +++---
 docs/system/arm/xlnx-zynq.rst        |  2 +-
 docs/system/guest-loader.rst         |  2 +-
 12 files changed, 77 insertions(+), 39 deletions(-)

-- 
2.48.1

[PATCH v2 2/3] 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>
---
v2: address Marc Zyngier's comments:
    https://lists.gnu.org/archive/html/qemu-devel/2025-01/msg03451.html
---
 docs/system/arm/cpu-features.rst | 46 +++++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 4 deletions(-)

diff --git a/docs/system/arm/cpu-features.rst b/docs/system/arm/cpu-features.rst
index a596316384..94d260b573 100644
--- a/docs/system/arm/cpu-features.rst
+++ b/docs/system/arm/cpu-features.rst
@@ -204,11 +204,49 @@ 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.  It aims to protect against ROP
+(return-oriented programming) attacks.
+
+KVM
+---
+
+``pauth``
+
+  Enable or disable ``FEAT_Pauth``.  No other properties can be
+  controlled.
+
+  The host CPU will define the PAC (pointer authentication
+  code) cryptographic algorithm.
+
+  There are different "levels" of PAuth support.  The host CPU
+  definition will define that level (e.g. PAuth, EPAC, PAuth2, FPAC,
+  FPACCOMBINE, etc).  Refer to the Arm architecture extension documents
+  for details about the description of these features.
+
+Live migration and PAuth
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The level of PAuth support depends on which Arm architecture a given CPU
+supports (e.g. Armv8.3 vs. Armv8.6).  This gradation in PAuth support
+has implications for live migration.  For example, to be able to
+live-migrate from host-A (with Armv8.3) to host-B (with Arm v8.6):
+
+  - the source and destination hosts must "agree" on (a) the PAC
+    signature algorithm, and (b) all the sub-features of PAuth; or
+
+  - the alternative (and less desirable) option is to turn off PAuth
+    off on both source and destination — this is generally not
+    recommended, as PAuth is a security feature.
+
+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 v2 2/3] docs/cpu-features: Update "PAuth" (Pointer Authentication) details

[Alex Bennée]

Kashyap Chamarthy <kchamart@redhat.com> writes:

> 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>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro