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

[Gerd Bayer]

On Tue, 2026-04-07 at 15:24 +0200, 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_checking 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.
> 
> Reviewed-by: Farhan Ali <alifm@xxxxxxxxxxxxx>
> Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> Reviewed-by: Matthew Rosato <mjrosato@xxxxxxxxxxxxx>
> Signed-off-by: Niklas Schnelle <schnelle@xxxxxxxxxxxxx>
> ---
>  Documentation/arch/s390/pci.rst | 144 +++++++++++++++++++++++++++-------------
>  1 file changed, 97 insertions(+), 47 deletions(-)
> 
> diff --git a/Documentation/arch/s390/pci.rst b/Documentation/arch/s390/pci.rst
> index d5755484d8e75c7bf67a350e61bbe04f0452a2fa..c3476de4f03278d07099aa32cbea0f868b6e9c9c 100644
> --- a/Documentation/arch/s390/pci.rst
> +++ b/Documentation/arch/s390/pci.rst
> @@ -6,6 +6,7 @@ S/390 PCI
>  
>  Authors:
>          - Pierre Morel
> +        - Niklas Schnelle
>  
>  Copyright, IBM Corp. 2020
>  
> @@ -27,14 +28,16 @@ Command line parameters
>  debugfs entries
>  ---------------
>  
> -The S/390 debug feature (s390dbf) generates views to hold various debug results in sysfs directories of the form:
> +The S/390 debug feature (s390dbf) generates views to hold various debug results
> +in sysfs directories of the form:
>  
>   * /sys/kernel/debug/s390dbf/pci_*/
>  
>  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
> @@ -47,87 +50,134 @@ Sysfs entries
>  
>  Entries specific to zPCI functions and entries that hold zPCI information.
>  
> -* /sys/bus/pci/slots/XXXXXXXX
> +* /sys/bus/pci/slots/XXXXXXXX:
>  
> -  The slot entries are set up using the function identifier (FID) of the
> -  PCI function. The format depicted as XXXXXXXX above is 8 hexadecimal digits
> -  with 0 padding and lower case hexadecimal digits.
> +  The slot entries are set up using the function identifier (FID) of the PCI
> +  function as slot name. The format depicted as XXXXXXXX above is 8 hexadecimal
> +  digits with 0 padding and lower case hexadecimal digits.
>  
>    - /sys/bus/pci/slots/XXXXXXXX/power
>  
>    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
> +  echo 0 > /sys/bus/pci/devices/DDDD:BB:dd.f/sriov_numvf
>  
> -* /sys/bus/pci/devices/XXXX:XX:XX.X/
> +* /sys/bus/pci/devices/DDDD:BB:dd.f/:
>  
> -  - function_id
> -    A zPCI function identifier that uniquely identifies the function in the Z server.
> +  - function_id:
> +    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
> -    Low-level identifier used for a configured PCI function.
> -    It might be useful for debugging.
> +  - function_handle:
> +    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
> -    Model-dependent location of the I/O adapter.
> +  - pchid:
> +    This 16-bit hexadecimal value encodes a model-dependent location for
> +    the PCI function.
>  
> -  - pfgid
> -    PCI function group ID, functions that share identical functionality
> +  - pfgid:
> +    PCI function group ID; functions that share identical functionality
>      use a common identifier.
>      A PCI group defines interrupts, IOMMU, IOTLB, and DMA specifics.
>  
> -  - vfn
> +  - vfn:
>      The virtual function number, from 1 to N for virtual functions,
>      0 for physical functions.
>  
> -  - pft
> -    The PCI function type
> +  - pft:
> +    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
> +    apart from unclassified functions (pft is 0x00) the same pft value
> +    generally implies a similar usage model. At the same time the same
> +    PCI hardware device may appear with different pft values when in a
> +    different usage model. For example NETD and NETH VFs may be implemented
> +    by the same PCI hardware device but in NETD the parent Physical Function
> +    is user managed while with NETH it is platform managed.
>  
> -  - port
> -    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.
> +    Currently the following PFT values are defined:
>  
> -  - uid
> -    The user identifier (UID) may be defined as part of the machine
> -    configuration or the z/VM or KVM guest configuration. If the accompanying
> -    uid_is_unique attribute is 1 the platform guarantees that the UID is unique
> -    within that instance and no devices with the same UID can be attached
> -    during the lifetime of the system.
> +    - 0x00 (UNC): Unclassified
> +    - 0x02 (ROCE): RoCE Express
> +    - 0x05 (ISM): Internal Shared Memory
> +    - 0x0a (ROC2): RoCE Express 2
> +    - 0x0b (NVMe): NVMe
> +    - 0x0c (NETH): Network Express hybrid
> +    - 0x0d (CNW): Cloud Network Adapter
> +    - 0x0f (NETD): Network Express direct
>  
> -  - uid_is_unique
> -    Indicates whether the user identifier (UID) is guaranteed to be and remain
> -    unique within this Linux instance.
> +  - port:
> +    The port is a decimal value corresponding to the physical port the function
> +    is attached to. Virtual Functions (VFs) share the port with their parent
> +    Physical Function (PF). A value of 0 indicates that the port attribute is
> +    not applicable for that PCI function type.
>  
> -  - pfip/segmentX
> +  - uid:
> +    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
> +    and no two PCI functions with the same UID will be visible to the instance.
> +
> +    Independent of this guarantee and unlike the function ID (FID) the UID may
> +    be the same in different partitions within the same machine. This allows to
> +    create PCI configurations in multiple partitions to be identical in the
> +    UID-namespace.
> +
> +  - uid_is_unique:
> +    A 0 or 1 flag indicating whether the user-defined identifier (UID) is
> +    guaranteed to be and remain unique within this Linux instance. This
> +    platform feature is called UID Checking.
> +
> +  - pfip/segmentX:
>      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.
>  
> +  - fidparm:
> +    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.
> +
> +* /sys/firmware/clp/uid_checking:
> +
> +  In addition to the per-device uid_is_unique attribute this presents a
> +  global indication of whether UID Checking is enabled. This allows users
> +  to check for UID Checking even when no PCI functions are configured.
> +
>  Enumeration and hotplug
>  =======================
>  
>  The PCI address consists of four parts: domain, bus, device and function,
> -and is of this form: DDDD:BB:dd.f
> +and is of this form: DDDD:BB:dd.f.
>  
> -* When not using multi-functions (norid is set, or the firmware does not
> -  support multi-functions):
> +* 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
> +  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 as defined during the
> -    LPAR creation.
> +  - 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.
>  
> -* When using multi-functions (norid parameter is not set),
> -  zPCI functions are addressed differently:
> +* For a PCI function for which the platform exposes the RID and which
> +  is not an Isolated Virtual Function:
>  
>    - There is still only one bus per domain.
>  
> -  - There can be up to 256 functions per bus.
> +  - There can be up to 256 PCI functions per bus.
>  
> -  - 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.
> +  - The domain part of the address of all functions within the same topology is
> +    that of the configured PCI function with the lowest devfn within that
> +    topology.
>  
> -  - New functions will only be ready for use after the function zero
> -    (the function with devfn 0) has been enumerated.
> +  - Virtual Functions generated by an SR-IOV capable Physical Function only
> +    become visible once SR-IOV is enabled.


LGTM!
Reviewed-by: Gerd Bayer <gbayer@xxxxxxxxxxxxx>