Re: [PATCH v6 1/2] docs: s390/pci: Improve and update PCI documentation

[Randy Dunlap]

Hi,

On 4/2/26 1:34 PM, Niklas Schnelle wrote:
> Update the s390 specific PCI documentation to better reflect current
> behavior and terms such as the handling of Isolated VFs via commit
> 25f39d3dcb48 ("s390/pci: Ignore RID for isolated VFs").
> 
> Add a descriptions for /sys/firmware/clp/uid_is_unique which was added
> in commit b043a81ce3ee ("s390/pci: Expose firmware provided UID Checking
> state in sysfs") but missed documentation.
> 
> Similarly add documentation for the fidparm attribute added by commit
> 99ad39306a62 ("s390/pci: Expose FIDPARM attribute in sysfs") and
> add a list of pft values and their names.
> 
> Finally improve formatting of the different attribute descriptions by
> adding a separating colon.
> 
> Signed-off-by: Niklas Schnelle <schnelle@xxxxxxxxxxxxx>
> ---
>  Documentation/arch/s390/pci.rst | 139 +++++++++++++++++++++++++++-------------
>  1 file changed, 94 insertions(+), 45 deletions(-)


These changes are good, so:
Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>


However, I would go a little farther and add these changes if you
are OK with them. (Patch applies after both of your patches.)

-- 
Signed-off-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
---
 Documentation/arch/s390/pci.rst |   25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

--- linux-next-20260401.orig/Documentation/arch/s390/pci.rst
+++ linux-next-20260401/Documentation/arch/s390/pci.rst
@@ -36,7 +36,8 @@ in sysfs directories of the form:
 For example:
 
   - /sys/kernel/debug/s390dbf/pci_msg/sprintf
-    Holds messages from the processing of PCI events, like machine check handling
+
+    holds messages from the processing of PCI events, like machine check handling
     and setting of global functionality, like UID checking.
 
   Change the level of logging to be more or less verbose by piping
@@ -57,8 +58,8 @@ Entries specific to zPCI functions and e
 
   - /sys/bus/pci/slots/XXXXXXXX/power
 
-  In addition to using the FID as the name of the slot the slot directory
-  also contains the following s390 specific slot attributes.
+  In addition to using the FID as the name of the slot, the slot directory
+  also contains the following s390-specific slot attributes.
 
   - uid:
     The User-defined identifier (UID) of the function which may be configured
@@ -71,22 +72,22 @@ Entries specific to zPCI functions and e
 * /sys/bus/pci/devices/DDDD:BB:dd.f/:
 
   - function_id:
-    The zPCI function identifier (FID) is a 32 bit hexadecimal value that
+    The zPCI function identifier (FID) is a 32-bit hexadecimal value that
     uniquely identifies the PCI function. Unless the hypervisor provides
     a virtual FID e.g. on KVM this identifier is unique across the machine even
     between different partitions.
 
   - function_handle:
-    This 32 bit hexadecimal value is a low-level identifier used for a PCI
+    This 32-bit hexadecimal value is a low-level identifier used for a PCI
     function. Note that the function handle may be changed and become invalid
     on PCI events and when enabling/disabling the PCI function.
 
   - pchid:
-    This 16 bit hexadecimal value encodes a model-dependent location for
+    This 16-bit hexadecimal value encodes a model-dependent location for
     the PCI function.
 
   - pfgid:
-    PCI function group ID, functions that share identical functionality
+    PCI function group ID; functions that share identical functionality
     use a common identifier.
     A PCI group defines interrupts, IOMMU, IOTLB, and DMA specifics.
 
@@ -95,7 +96,7 @@ Entries specific to zPCI functions and e
     0 for physical functions.
 
   - pft:
-    The PCI function type is an s390 specific type attribute. It indicates
+    The PCI function type is an s390-specific type attribute. It indicates
     a more general, usage oriented, type than PCI Specification
     class/vendor/device identifiers. That is PCI functions with the same pft
     value may be backed by different hardware implementations. At the same time
@@ -124,7 +125,7 @@ Entries specific to zPCI functions and e
     not applicable for that PCI function type.
 
   - uid:
-    The user-defined identifier (UID) for a PCI function is a 32 bit
+    The user-defined identifier (UID) for a PCI function is a 32-bit
     hexadecimal value. It is defined on a per instance basis as part of the
     partition, KVM guest, or z/VM guest configuration. If UID Checking is
     enabled the platform ensures that the UID is unique within that instance
@@ -146,7 +147,7 @@ Entries specific to zPCI functions and e
     The more the segments are different, the more the functions are isolated.
 
   - fidparm:
-    Contains an 8 bit per PCI function parameter field in hexadecimal provided
+    Contains an 8-bit-per-PCI function parameter field in hexadecimal provided
     by the platform. The meaning of this field is PCI function type specific.
     For NETH VFs a value of 0x01 indicates that the function supports
     promiscuous mode.
@@ -164,13 +165,13 @@ The PCI address consists of four parts:
 and is of this form: DDDD:BB:dd.f.
 
 * For a PCI function for which the platform does not expose the RID, the
-  pci=norid kernel parameter is used, or a so called isolated Virtual Function
+  pci=norid kernel parameter is used, or a so-called isolated Virtual Function
   which does have RID information but is used without its parent Physical
   Function being part of the same PCI configuration:
 
   - There is only one function per domain.
 
-  - The domain is set from the zPCI function's UID if UID Checking is on
+  - The domain is set from the zPCI function's UID if UID Checking is on;
     otherwise the domain ID is generated dynamically and is not stable
     across reboots or hot plug.