1.. SPDX-License-Identifier: GPL-2.0 2 3========= 4S/390 PCI 5========= 6 7Authors: 8 - Pierre Morel 9 - Niklas Schnelle 10 11Copyright, IBM Corp. 2020 12 13 14Command line parameters and debugfs entries 15=========================================== 16 17Command line parameters 18----------------------- 19 20* nomio 21 22 Do not use PCI Mapped I/O (MIO) instructions. 23 24* norid 25 26 Ignore the RID field and force use of one PCI domain per PCI function. 27 28debugfs entries 29--------------- 30 31The S/390 debug feature (s390dbf) generates views to hold various debug results 32in sysfs directories of the form: 33 34 * /sys/kernel/debug/s390dbf/pci_*/ 35 36For example: 37 38 - /sys/kernel/debug/s390dbf/pci_msg/sprintf 39 40 holds messages from the processing of PCI events, like machine check handling 41 and setting of global functionality, like UID checking. 42 43 Change the level of logging to be more or less verbose by piping 44 a number between 0 and 6 to /sys/kernel/debug/s390dbf/pci_*/level. For 45 details, see the documentation on the S/390 debug feature at 46 Documentation/arch/s390/s390dbf.rst. 47 48Sysfs entries 49============= 50 51Entries specific to zPCI functions and entries that hold zPCI information. 52 53* /sys/bus/pci/slots/XXXXXXXX: 54 55 The slot entries are set up using the function identifier (FID) of the PCI 56 function as slot name. The format depicted as XXXXXXXX above is 8 hexadecimal 57 digits with 0 padding and lower case hexadecimal digits. 58 59 - /sys/bus/pci/slots/XXXXXXXX/power 60 61 In addition to using the FID as the name of the slot, the slot directory 62 also contains the following s390-specific slot attributes. 63 64 - uid: 65 The User-defined identifier (UID) of the function which may be configured 66 by this slot. See also the corresponding attribute of the device. 67 68 A physical function that currently supports a virtual function cannot be 69 powered off until all virtual functions are removed with: 70 echo 0 > /sys/bus/pci/devices/DDDD:BB:dd.f/sriov_numvf 71 72* /sys/bus/pci/devices/DDDD:BB:dd.f/: 73 74 - function_id: 75 The zPCI function identifier (FID) is a 32-bit hexadecimal value that 76 uniquely identifies the PCI function. Unless the hypervisor provides 77 a virtual FID e.g. on KVM this identifier is unique across the machine even 78 between different partitions. 79 80 - function_handle: 81 This 32-bit hexadecimal value is a low-level identifier used for a PCI 82 function. Note that the function handle may be changed and become invalid 83 on PCI events and when enabling/disabling the PCI function. 84 85 - pchid: 86 This 16-bit hexadecimal value encodes a model-dependent location for 87 the PCI function. 88 89 - pfgid: 90 PCI function group ID; functions that share identical functionality 91 use a common identifier. 92 A PCI group defines interrupts, IOMMU, IOTLB, and DMA specifics. 93 94 - vfn: 95 The virtual function number, from 1 to N for virtual functions, 96 0 for physical functions. 97 98 - pft: 99 The PCI function type is an s390-specific type attribute. It indicates 100 a more general, usage oriented, type than PCI Specification 101 class/vendor/device identifiers. That is PCI functions with the same pft 102 value may be backed by different hardware implementations. At the same time 103 apart from unclassified functions (pft is 0x00) the same pft value 104 generally implies a similar usage model. At the same time the same 105 PCI hardware device may appear with different pft values when in a 106 different usage model. For example NETD and NETH VFs may be implemented 107 by the same PCI hardware device but in NETD the parent Physical Function 108 is user managed while with NETH it is platform managed. 109 110 Currently the following PFT values are defined: 111 112 - 0x00 (UNC): Unclassified 113 - 0x02 (ROCE): RoCE Express 114 - 0x05 (ISM): Internal Shared Memory 115 - 0x0a (ROC2): RoCE Express 2 116 - 0x0b (NVMe): NVMe 117 - 0x0c (NETH): Network Express hybrid 118 - 0x0d (CNW): Cloud Network Adapter 119 - 0x0f (NETD): Network Express direct 120 121 - port: 122 The port is a decimal value corresponding to the physical port the function 123 is attached to. Virtual Functions (VFs) share the port with their parent 124 Physical Function (PF). A value of 0 indicates that the port attribute is 125 not applicable for that PCI function type. 126 127 - uid: 128 The user-defined identifier (UID) for a PCI function is a 32-bit 129 hexadecimal value. It is defined on a per instance basis as part of the 130 partition, KVM guest, or z/VM guest configuration. If UID Checking is 131 enabled the platform ensures that the UID is unique within that instance 132 and no two PCI functions with the same UID will be visible to the instance. 133 134 Independent of this guarantee and unlike the function ID (FID) the UID may 135 be the same in different partitions within the same machine. This allows to 136 create PCI configurations in multiple partitions to be identical in the 137 UID-namespace. 138 139 - uid_is_unique: 140 A 0 or 1 flag indicating whether the user-defined identifier (UID) is 141 guaranteed to be and remain unique within this Linux instance. This 142 platform feature is called UID Checking. 143 144 - pfip/segmentX: 145 The segments determine the isolation of a function. 146 They correspond to the physical path to the function. 147 The more the segments are different, the more the functions are isolated. 148 149 - fidparm: 150 Contains an 8-bit-per-PCI function parameter field in hexadecimal provided 151 by the platform. The meaning of this field is PCI function type specific. 152 For NETH VFs a value of 0x01 indicates that the function supports 153 promiscuous mode. 154 155* /sys/firmware/clp/uid_checking: 156 157 In addition to the per-device uid_is_unique attribute this presents a 158 global indication of whether UID Checking is enabled. This allows users 159 to check for UID Checking even when no PCI functions are configured. 160 161Enumeration and hotplug 162======================= 163 164The PCI address consists of four parts: domain, bus, device and function, 165and is of this form: DDDD:BB:dd.f. 166 167* For a PCI function for which the platform does not expose the RID, the 168 pci=norid kernel parameter is used, or a so-called isolated Virtual Function 169 which does have RID information but is used without its parent Physical 170 Function being part of the same PCI configuration: 171 172 - There is only one function per domain. 173 174 - The domain is set from the zPCI function's UID if UID Checking is on; 175 otherwise the domain ID is generated dynamically and is not stable 176 across reboots or hot plug. 177 178* For a PCI function for which the platform exposes the RID and which 179 is not an Isolated Virtual Function: 180 181 - There is still only one bus per domain. 182 183 - There can be up to 256 PCI functions per bus. 184 185 - The domain part of the address of all functions within the same topology is 186 that of the configured PCI function with the lowest devfn within that 187 topology. 188 189 - Virtual Functions generated by an SR-IOV capable Physical Function only 190 become visible once SR-IOV is enabled. 191