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.
54
55  - /sys/bus/pci/slots/XXXXXXXX/power
56
57  A physical function that currently supports a virtual function cannot be
58  powered off until all virtual functions are removed with:
59  echo 0 > /sys/bus/pci/devices/XXXX:XX:XX.X/sriov_numvf
60
61* /sys/bus/pci/devices/XXXX:XX:XX.X/
62
63  - function_id
64    A zPCI function identifier that uniquely identifies the function in the Z server.
65
66  - function_handle
67    Low-level identifier used for a configured PCI function.
68    It might be useful for debuging.
69
70  - pchid
71    Model-dependent location of the I/O adapter.
72
73  - pfgid
74    PCI function group ID, functions that share identical functionality
75    use a common identifier.
76    A PCI group defines interrupts, IOMMU, IOTLB, and DMA specifics.
77
78  - vfn
79    The virtual function number, from 1 to N for virtual functions,
80    0 for physical functions.
81
82  - pft
83    The PCI function type
84
85  - port
86    The port corresponds to the physical port the function is attached to.
87    It also gives an indication of the physical function a virtual function
88    is attached to.
89
90  - uid
91    The unique identifier (UID) is defined when configuring an LPAR and is
92    unique in the LPAR.
93
94  - pfip/segmentX
95    The segments determine the isolation of a function.
96    They correspond to the physical path to the function.
97    The more the segments are different, the more the functions are isolated.
98
99Enumeration and hotplug
100=======================
101
102The PCI address consists of four parts: domain, bus, device and function,
103and is of this form: DDDD:BB:dd.f
104
105* When not using multi-functions (norid is set, or the firmware does not
106  support multi-functions):
107
108  - There is only one function per domain.
109
110  - The domain is set from the zPCI function's UID as defined during the
111    LPAR creation.
112
113* When using multi-functions (norid parameter is not set),
114  zPCI functions are addressed differently:
115
116  - There is still only one bus per domain.
117
118  - There can be up to 256 functions per bus.
119
120  - The domain part of the address of all functions for
121    a multi-Function device is set from the zPCI function's UID as defined
122    in the LPAR creation for the function zero.
123
124  - New functions will only be ready for use after the function zero
125    (the function with devfn 0) has been enumerated.
126