s390/pci: Documentation update for s390 PCI

Clarify the documentation.

Signed-off-by: Pierre Morel <pmorel@linux.ibm.com>
Reviewed-by: Niklas Schnelle <schnelle@linux.ibm.com>
Signed-off-by: Vasily Gorbik <gor@linux.ibm.com>

Documentation/s390/pci.rst

@@ -10,7 +10,7 @@ Authors:
 Copyright, IBM Corp. 2020
 
 
-command line parameters and debugfs entries
+Command line parameters and debugfs entries
 ===========================================
 
 Command line parameters
@@ -18,7 +18,7 @@ Command line parameters
 
 * nomio
 
-  Do not use MIO instructions.
+  Do not use PCI Mapped I/O (MIO) instructions.
 
 * norid
 
@@ -27,100 +27,99 @@ Command line parameters
 debugfs entries
 ---------------
 
-* /sys/kernel/debug/s390dbf/pci_*/ (S/390 debug feature)
+The S/390 debug feature (s390dbf) generates views to hold various debug results in sysfs directories of the form:
 
-  Some views generated by the debug feature to hold various debug outputs.
+ * /sys/kernel/debug/s390dbf/pci_*/
+
+For example:
 
   - /sys/kernel/debug/s390dbf/pci_msg/sprintf
-    Messages from the processing of PCI events like machine check handling
-    and setting of global functionality like UID checking.
+    Holds messages from the processing of PCI events, like machine check handling
+    and setting of global functionality, like UID checking.
 
-  The level of logging can be changed to be more or less verbose by piping to
-  /sys/kernel/debug/s390dbf/pci_*/level a number between 0 and 6; see the
-  documentation on the S/390 debug feature (Documentation/s390/s390dbf.rst)
-  for details.
+  Change the level of logging to be more or less verbose by piping
+  a number between 0 and 6 to  /sys/kernel/debug/s390dbf/pci_*/level. For
+  details, see the documentation on the S/390 debug feature at
+  Documentation/s390/s390dbf.rst.
 
 Sysfs entries
 =============
 
-Specific entries, or entries specificities for zPCI functions.
+Entries specific to zPCI functions and entries that hold zPCI information.
 
 * /sys/bus/pci/slots/XXXXXXXX
 
-  The slot entries are setup using the FID (Function Identifier) of the
+  The slot entries are set up using the function identifier (FID) of the
   PCI function.
 
   - /sys/bus/pci/slots/XXXXXXXX/power
 
-  A physical function currently supporting virtual function can not be
-  powered-off until all virtual-function have been removed with
+  A physical function that currently supports a virtual function cannot be
+  powered off until all virtual functions are removed with:
   echo 0 > /sys/bus/pci/devices/XXXX:XX:XX.X/sriov_numvf
 
 * /sys/bus/pci/devices/XXXX:XX:XX.X/
 
   - function_id
-    zPCI function identifier unique for the complete Z System.
-    It define uniquely a function in the system.
+    A zPCI function identifier that uniquely identifies the function in the Z server.
 
   - function_handle
-    Low level identifier used for a configured PCI function.
-    It may be useful for debuging.
+    Low-level identifier used for a configured PCI function.
+    It might be useful for debuging.
 
   - pchid
-    Model dependent location of the I/O adapter.
+    Model-dependent location of the I/O adapter.
 
   - pfgid
-    PCI Function Group ID, functions sharing identical functionality
-    are using a common identifier.
-    A PCI group defines interrupts, IOMMU, IOTLB and DMA specifics.
+    PCI function group ID, functions that share identical functionality
+    use a common identifier.
+    A PCI group defines interrupts, IOMMU, IOTLB, and DMA specifics.
 
   - vfn
-    The Virtual Function Number, from 1 to N for virtual functions.
+    The virtual function number, from 1 to N for virtual functions,
     0 for physical functions.
 
   - pft
-    PCI function type specifies the type of the PCI function.
+    The PCI function type
 
   - port
-    The port correspond to the physical port the function is attached to.
-    It also gives an indication on the physical function a virtual function
+    The port corresponds to the physical port the function is attached to.
+    It also gives an indication of the physical function a virtual function
     is attached to.
 
   - uid
-    The UID, Unique Identifier is defined when configuring a LPAR and is
-    unique inside an LPAR.
+    The unique identifier (UID) is defined when configuring an LPAR and is
+    unique in the LPAR.
 
   - pfip/segmentX
-    The segments are used to determine the isolation of a function.
-    They corresponds to the physical path to the function.
-    The more the segment are different the more the functions are isolated.
+    The segments determine the isolation of a function.
+    They correspond to the physical path to the function.
+    The more the segments are different, the more the functions are isolated.
 
 Enumeration and hotplug
 =======================
 
-The PCI address is made of 4 parts: domain, bus, device and function,
-like in DDDD:BB:dd.f
+The PCI address consists of four parts: domain, bus, device and function,
+and is of this form: DDDD:BB:dd.f
 
-* When not using multi-functions (norid is set or firmware does not support
-  multi-functions)
+* When not using multi-functions (norid is set, or the firmware does not
+  support multi-functions):
 
   - There is only one function per domain.
 
-  - the domain is set from the zPCI function's UID as defined during the
+  - The domain is set from the zPCI function's UID as defined during the
     LPAR creation.
 
-  - Addresses look like DDDD:00:00.0
-
-* When using multi-functions (norid parameter is not set), there are some
-  change in the way zPCI functions are addressed:
+* When using multi-functions (norid parameter is not set),
+  zPCI functions are addressed differently:
 
   - There is still only one bus per domain.
 
   - There can be up to 256 functions per bus.
 
-  - The domain part of the address of all functions of all functions for
+  - The domain part of the address of all functions for
     a multi-Function device is set from the zPCI function's UID as defined
     in the LPAR creation for the function zero.
 
-  - New functions will only be ready to be used after the function zero
+  - New functions will only be ready for use after the function zero
     (the function with devfn 0) has been enumerated.