s390/pci: Documentation update for s390 PCI

Copyright, IBM Corp. 2020

command line parameters and debugfs entries

Command line parameters and debugfs entries

===========================================

Command line parameters

* nomio

  Do not use MIO instructions.

  Do not use PCI Mapped I/O (MIO) instructions.

* norid

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.