Re: [PATCH v4 15/15] s390/vfio-ap: Add live guest migration chapter to vfio-ap.rst

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] The newly added documentation for live guest migration contains multiple typos, grammatical issues, factual errors, and ReST formatting problems.
--

--- Patch [15]: [PATCH v4 15/15] s390/vfio-ap: Add live guest migration chapter to vfio-ap.rst ---
commit e1db7dba8604c95334563aa2130ba1fa4ead1210
Author: Anthony Krowiak <akrowiak@linux.ibm.com>
s390/vfio-ap: Add live guest migration chapter to vfio-ap.rst

Add a 'Live Guest Migration' chapter to the
Documentation/arch/s390/vfio-ap.rst document to describe the details for
initiating live guest migration for a guest to which AP adapters, domains
and control domains have been passed through.

> diff --git a/Documentation/arch/s390/vfio-ap.rst b/Documentation/arch/s390/vfio-ap.rst
> index ac0c07f76ddd7..fc0707c0dffd6 100644
> --- a/Documentation/arch/s390/vfio-ap.rst
> +++ b/Documentation/arch/s390/vfio-ap.rst
[ ... ]
> +  * Display the AP configuration of the destination host:
> +
> +    .. code-block:: bash
> +
> +       lszcrypt -V
> +       cat /sys/bus/ap/ap_control_domain_mask
> +
> +    Note that each bit in the ap_control_domain_mask corresponds to
> +    correspond to domain numbers 0-255. If a bit is set to one, then
> +    the control domain is available on the destination host. For
> +    example:
> +
> +    .. code-block:: bash
> +
> +       0x0000000000001020000000000000000000000000000000000000000000000000
> +
> +       This mask indicates that AP adapters 51 (0x33) and 58 (0x58) are
> +       available on the host system.

[Severity: Low]
This isn't a bug, but there are a couple of inaccuracies in this sentence.

Since we are examining `ap_control_domain_mask`, shouldn't this refer to
"AP control domains" rather than "AP adapters"?

Also, the hexadecimal value for 58 is 0x3a, not 0x58.

[ ... ]
> +  * Verify the hardware capabilities for each AP adapter device on the source
> +    and destination host are compatible. The ``ap_functions`` attribute is a
> +    bitmask. The bits in the mask read from left to right starting with bit 0.
> +    Each bit that is set to one indicates the corresponding hardware capability
> +    is installed:
> +
> +    * Bits 0-3 are the facilities bits. Each bit value must match for the AP
> +      devices on the source and destination systems. The values indicate the
> +      following:
> +      * bit-0: APSC is installed
> +      * bit-1: AP4KM is installed
> +      * bit-2: AP4KC is installed

[Severity: Low]
This isn't a bug, but there is a missing blank line before this nested list
that might cause incorrect Sphinx rendering.

Should there be a blank line after "The values indicate the following:"?

> +
> +    * Bits 3-5 specify the adapter Modes. Only one of these bits will be set to

[Severity: Low]
This isn't a bug, but there is an overlap in the bit ranges described here.

The facilities bits are described as Bits 0-3, but the adapter modes start
at Bit 3.

Should the facilities bits be 0-2?

> +      one and must be the same for both the source and destination adapter
> +      devices:
> +      * bit-3: CCA-mode
> +      * bit-4: Accelerator-mode
> +      * bit-5: XCP-mode (EP11)
> +
> +    * Bit 6 specifies whether APXA is installed and must be the same for both
> +      the source and destination adapter devices.
> +
> +    * Bit 7 specifies command whether command filtering is installed

[Severity: Low]
This isn't a bug, but there is a grammatical error here.

Could this be updated to remove the extra "command" ("specifies whether
command filtering")?

> +      and must be the same for both the source and destination adapter devices.
[ ... ]
> +Reserve adapters and domains for the vfio_ap device driver's use
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Reserve the same adapters and domains passed through to the source guest
> +for the vfio_ap device driver on the destination host by clearing the
> +adapter numbers from the ``/sys/bus/ap/ap_mask`` and/or the domain numbers

[Severity: Low]
This isn't a bug, but the sysfs path here seems incorrect.

Should this be `/sys/bus/ap/apmask` instead of `/sys/bus/ap/ap_mask` to
match the actual sysfs entry?

> +from the ``/sys/bus/ap/aqmask`` files.
[ ... ]
> +**Destinaton host**

[Severity: Low]
This isn't a bug, but there is a typo here ("Destinaton" instead of
"Destination").

[ ... ]
> +The AP configurations of the source guest and destination host not incompatible
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[Severity: Low]
This isn't a bug, but the section heading might be confusing.

Should it read "are incompatible" instead of "not incompatible"?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260707090226.3206695-1-akrowiak@linux.ibm.com?part=15