Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: s390/pci: Improve and update PCI documentation
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@linux.ibm.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Matthew Rosato <mjrosato@linux.ibm.com>
Signed-off-by: Niklas Schnelle <schnelle@linux.ibm.com>
Reviewed-by: Gerd Bayer <gbayer@linux.ibm.com>
Link: https://lore.kernel.org/r/20260407-uid_slot-v8-1-15ae4409d2ce@linux.ibm.com
Signed-off-by: Vasily Gorbik <gor@linux.ibm.com>
authored by
Niklas Schnelle
and committed by
Vasily Gorbik
737c4f4a
e3d074b5
+97
-47
+97
-47
Documentation/arch/s390/pci.rst
+97
-47
Documentation/arch/s390/pci.rst
···
6
6
7
7
Authors:
8
8
- Pierre Morel
9
+
- Niklas Schnelle
9
10
10
11
Copyright, IBM Corp. 2020
11
12
···
28
27
debugfs entries
29
28
---------------
30
29
31
-
The S/390 debug feature (s390dbf) generates views to hold various debug results in sysfs directories of the form:
30
+
The S/390 debug feature (s390dbf) generates views to hold various debug results
31
+
in sysfs directories of the form:
32
32
33
33
* /sys/kernel/debug/s390dbf/pci_*/
34
34
35
35
For example:
36
36
37
37
- /sys/kernel/debug/s390dbf/pci_msg/sprintf
38
-
Holds messages from the processing of PCI events, like machine check handling
38
+
39
+
holds messages from the processing of PCI events, like machine check handling
39
40
and setting of global functionality, like UID checking.
40
41
41
42
Change the level of logging to be more or less verbose by piping
···
50
47
51
48
Entries specific to zPCI functions and entries that hold zPCI information.
52
49
53
-
* /sys/bus/pci/slots/XXXXXXXX
50
+
* /sys/bus/pci/slots/XXXXXXXX:
54
51
55
-
The slot entries are set up using the function identifier (FID) of the
56
-
PCI function. The format depicted as XXXXXXXX above is 8 hexadecimal digits
57
-
with 0 padding and lower case hexadecimal digits.
52
+
The slot entries are set up using the function identifier (FID) of the PCI
53
+
function as slot name. The format depicted as XXXXXXXX above is 8 hexadecimal
54
+
digits with 0 padding and lower case hexadecimal digits.
58
55
59
56
- /sys/bus/pci/slots/XXXXXXXX/power
60
57
61
58
A physical function that currently supports a virtual function cannot be
62
59
powered off until all virtual functions are removed with:
63
-
echo 0 > /sys/bus/pci/devices/XXXX:XX:XX.X/sriov_numvf
60
+
echo 0 > /sys/bus/pci/devices/DDDD:BB:dd.f/sriov_numvf
64
61
65
-
* /sys/bus/pci/devices/XXXX:XX:XX.X/
62
+
* /sys/bus/pci/devices/DDDD:BB:dd.f/:
66
63
67
-
- function_id
68
-
A zPCI function identifier that uniquely identifies the function in the Z server.
64
+
- function_id:
65
+
The zPCI function identifier (FID) is a 32-bit hexadecimal value that
66
+
uniquely identifies the PCI function. Unless the hypervisor provides
67
+
a virtual FID e.g. on KVM this identifier is unique across the machine even
68
+
between different partitions.
69
69
70
-
- function_handle
71
-
Low-level identifier used for a configured PCI function.
72
-
It might be useful for debugging.
70
+
- function_handle:
71
+
This 32-bit hexadecimal value is a low-level identifier used for a PCI
72
+
function. Note that the function handle may be changed and become invalid
73
+
on PCI events and when enabling/disabling the PCI function.
73
74
74
-
- pchid
75
-
Model-dependent location of the I/O adapter.
75
+
- pchid:
76
+
This 16-bit hexadecimal value encodes a model-dependent location for
77
+
the PCI function.
76
78
77
-
- pfgid
78
-
PCI function group ID, functions that share identical functionality
79
+
- pfgid:
80
+
PCI function group ID; functions that share identical functionality
79
81
use a common identifier.
80
82
A PCI group defines interrupts, IOMMU, IOTLB, and DMA specifics.
81
83
82
-
- vfn
84
+
- vfn:
83
85
The virtual function number, from 1 to N for virtual functions,
84
86
0 for physical functions.
85
87
86
-
- pft
87
-
The PCI function type
88
+
- pft:
89
+
The PCI function type is an s390-specific type attribute. It indicates
90
+
a more general, usage oriented, type than PCI Specification
91
+
class/vendor/device identifiers. That is PCI functions with the same pft
92
+
value may be backed by different hardware implementations. At the same time
93
+
apart from unclassified functions (pft is 0x00) the same pft value
94
+
generally implies a similar usage model. At the same time the same
95
+
PCI hardware device may appear with different pft values when in a
96
+
different usage model. For example NETD and NETH VFs may be implemented
97
+
by the same PCI hardware device but in NETD the parent Physical Function
98
+
is user managed while with NETH it is platform managed.
88
99
89
-
- port
90
-
The port corresponds to the physical port the function is attached to.
91
-
It also gives an indication of the physical function a virtual function
92
-
is attached to.
100
+
Currently the following PFT values are defined:
93
101
94
-
- uid
95
-
The user identifier (UID) may be defined as part of the machine
96
-
configuration or the z/VM or KVM guest configuration. If the accompanying
97
-
uid_is_unique attribute is 1 the platform guarantees that the UID is unique
98
-
within that instance and no devices with the same UID can be attached
99
-
during the lifetime of the system.
102
+
- 0x00 (UNC): Unclassified
103
+
- 0x02 (ROCE): RoCE Express
104
+
- 0x05 (ISM): Internal Shared Memory
105
+
- 0x0a (ROC2): RoCE Express 2
106
+
- 0x0b (NVMe): NVMe
107
+
- 0x0c (NETH): Network Express hybrid
108
+
- 0x0d (CNW): Cloud Network Adapter
109
+
- 0x0f (NETD): Network Express direct
100
110
101
-
- uid_is_unique
102
-
Indicates whether the user identifier (UID) is guaranteed to be and remain
103
-
unique within this Linux instance.
111
+
- port:
112
+
The port is a decimal value corresponding to the physical port the function
113
+
is attached to. Virtual Functions (VFs) share the port with their parent
114
+
Physical Function (PF). A value of 0 indicates that the port attribute is
115
+
not applicable for that PCI function type.
104
116
105
-
- pfip/segmentX
117
+
- uid:
118
+
The user-defined identifier (UID) for a PCI function is a 32-bit
119
+
hexadecimal value. It is defined on a per instance basis as part of the
120
+
partition, KVM guest, or z/VM guest configuration. If UID Checking is
121
+
enabled the platform ensures that the UID is unique within that instance
122
+
and no two PCI functions with the same UID will be visible to the instance.
123
+
124
+
Independent of this guarantee and unlike the function ID (FID) the UID may
125
+
be the same in different partitions within the same machine. This allows to
126
+
create PCI configurations in multiple partitions to be identical in the
127
+
UID-namespace.
128
+
129
+
- uid_is_unique:
130
+
A 0 or 1 flag indicating whether the user-defined identifier (UID) is
131
+
guaranteed to be and remain unique within this Linux instance. This
132
+
platform feature is called UID Checking.
133
+
134
+
- pfip/segmentX:
106
135
The segments determine the isolation of a function.
107
136
They correspond to the physical path to the function.
108
137
The more the segments are different, the more the functions are isolated.
138
+
139
+
- fidparm:
140
+
Contains an 8-bit-per-PCI function parameter field in hexadecimal provided
141
+
by the platform. The meaning of this field is PCI function type specific.
142
+
For NETH VFs a value of 0x01 indicates that the function supports
143
+
promiscuous mode.
144
+
145
+
* /sys/firmware/clp/uid_checking:
146
+
147
+
In addition to the per-device uid_is_unique attribute this presents a
148
+
global indication of whether UID Checking is enabled. This allows users
149
+
to check for UID Checking even when no PCI functions are configured.
109
150
110
151
Enumeration and hotplug
111
152
=======================
112
153
113
154
The PCI address consists of four parts: domain, bus, device and function,
114
-
and is of this form: DDDD:BB:dd.f
155
+
and is of this form: DDDD:BB:dd.f.
115
156
116
-
* When not using multi-functions (norid is set, or the firmware does not
117
-
support multi-functions):
157
+
* For a PCI function for which the platform does not expose the RID, the
158
+
pci=norid kernel parameter is used, or a so-called isolated Virtual Function
159
+
which does have RID information but is used without its parent Physical
160
+
Function being part of the same PCI configuration:
118
161
119
162
- There is only one function per domain.
120
163
121
-
- The domain is set from the zPCI function's UID as defined during the
122
-
LPAR creation.
164
+
- The domain is set from the zPCI function's UID if UID Checking is on;
165
+
otherwise the domain ID is generated dynamically and is not stable
166
+
across reboots or hot plug.
123
167
124
-
* When using multi-functions (norid parameter is not set),
125
-
zPCI functions are addressed differently:
168
+
* For a PCI function for which the platform exposes the RID and which
169
+
is not an Isolated Virtual Function:
126
170
127
171
- There is still only one bus per domain.
128
172
129
-
- There can be up to 256 functions per bus.
173
+
- There can be up to 256 PCI functions per bus.
130
174
131
-
- The domain part of the address of all functions for
132
-
a multi-Function device is set from the zPCI function's UID as defined
133
-
in the LPAR creation for the function zero.
175
+
- The domain part of the address of all functions within the same topology is
176
+
that of the configured PCI function with the lowest devfn within that
177
+
topology.
134
178
135
-
- New functions will only be ready for use after the function zero
136
-
(the function with devfn 0) has been enumerated.
179
+
- Virtual Functions generated by an SR-IOV capable Physical Function only
180
+
become visible once SR-IOV is enabled.