LXR linux/Documentation/s390/pci.rst

   1.. SPDX-License-Identifier: GPL-2.0
   2
   3=========
   4S/390 PCI
   5=========
   6
   7Authors:
   8        - Pierre Morel
   9
  10Copyright, IBM Corp. 2020
  11
  12
  13Command line parameters and debugfs entries
  14===========================================
  15
  16Command line parameters
  17-----------------------
  18
  19* nomio
  20
  21  Do not use PCI Mapped I/O (MIO) instructions.
  22
  23* norid
  24
  25  Ignore the RID field and force use of one PCI domain per PCI function.
  26
  27debugfs entries
  28---------------
  29
  30The S/390 debug feature (s390dbf) generates views to hold various debug results in sysfs directories of the form:
  31
  32 * /sys/kernel/debug/s390dbf/pci_*/
  33
  34For example:
  35
  36  - /sys/kernel/debug/s390dbf/pci_msg/sprintf
  37    Holds messages from the processing of PCI events, like machine check handling
  38    and setting of global functionality, like UID checking.
  39
  40  Change the level of logging to be more or less verbose by piping
  41  a number between 0 and 6 to  /sys/kernel/debug/s390dbf/pci_*/level. For
  42  details, see the documentation on the S/390 debug feature at
  43  Documentation/s390/s390dbf.rst.
  44
  45Sysfs entries
  46=============
  47
  48Entries specific to zPCI functions and entries that hold zPCI information.
  49
  50* /sys/bus/pci/slots/XXXXXXXX
  51
  52  The slot entries are set up using the function identifier (FID) of the
  53  PCI function. The format depicted as XXXXXXXX above is 8 hexadecimal digits
  54  with 0 padding and lower case hexadecimal digitis.
  55
  56  - /sys/bus/pci/slots/XXXXXXXX/power
  57
  58  A physical function that currently supports a virtual function cannot be
  59  powered off until all virtual functions are removed with:
  60  echo 0 > /sys/bus/pci/devices/XXXX:XX:XX.X/sriov_numvf
  61
  62* /sys/bus/pci/devices/XXXX:XX:XX.X/
  63
  64  - function_id
  65    A zPCI function identifier that uniquely identifies the function in the Z server.
  66
  67  - function_handle
  68    Low-level identifier used for a configured PCI function.
  69    It might be useful for debuging.
  70
  71  - pchid
  72    Model-dependent location of the I/O adapter.
  73
  74  - pfgid
  75    PCI function group ID, functions that share identical functionality
  76    use a common identifier.
  77    A PCI group defines interrupts, IOMMU, IOTLB, and DMA specifics.
  78
  79  - vfn
  80    The virtual function number, from 1 to N for virtual functions,
  81    0 for physical functions.
  82
  83  - pft
  84    The PCI function type
  85
  86  - port
  87    The port corresponds to the physical port the function is attached to.
  88    It also gives an indication of the physical function a virtual function
  89    is attached to.
  90
  91  - uid
  92    The user identifier (UID) may be defined as part of the machine
  93    configuration or the z/VM or KVM guest configuration. If the accompanying
  94    uid_is_unique attribute is 1 the platform guarantees that the UID is unique
  95    within that instance and no devices with the same UID can be attached
  96    during the lifetime of the system.
  97
  98  - uid_is_unique
  99    Indicates whether the user identifier (UID) is guaranteed to be and remain
 100    unique within this Linux instance.
 101
 102  - pfip/segmentX
 103    The segments determine the isolation of a function.
 104    They correspond to the physical path to the function.
 105    The more the segments are different, the more the functions are isolated.
 106
 107Enumeration and hotplug
 108=======================
 109
 110The PCI address consists of four parts: domain, bus, device and function,
 111and is of this form: DDDD:BB:dd.f
 112
 113* When not using multi-functions (norid is set, or the firmware does not
 114  support multi-functions):
 115
 116  - There is only one function per domain.
 117
 118  - The domain is set from the zPCI function's UID as defined during the
 119    LPAR creation.
 120
 121* When using multi-functions (norid parameter is not set),
 122  zPCI functions are addressed differently:
 123
 124  - There is still only one bus per domain.
 125
 126  - There can be up to 256 functions per bus.
 127
 128  - The domain part of the address of all functions for
 129    a multi-Function device is set from the zPCI function's UID as defined
 130    in the LPAR creation for the function zero.
 131
 132  - New functions will only be ready for use after the function zero
 133    (the function with devfn 0) has been enumerated.
 134