Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

s390/pci: Documentation update for s390 PCI

Clarify the documentation.

Signed-off-by: Pierre Morel <pmorel@linux.ibm.com>
Reviewed-by: Niklas Schnelle <schnelle@linux.ibm.com>
Signed-off-by: Vasily Gorbik <gor@linux.ibm.com>

authored by

Pierre Morel and committed by
Vasily Gorbik
9056754f d1379279

+41 -42
+41 -42
Documentation/s390/pci.rst
··· 10 10 Copyright, IBM Corp. 2020 11 11 12 12 13 - command line parameters and debugfs entries 13 + Command line parameters and debugfs entries 14 14 =========================================== 15 15 16 16 Command line parameters ··· 18 18 19 19 * nomio 20 20 21 - Do not use MIO instructions. 21 + Do not use PCI Mapped I/O (MIO) instructions. 22 22 23 23 * norid 24 24 ··· 27 27 debugfs entries 28 28 --------------- 29 29 30 - * /sys/kernel/debug/s390dbf/pci_*/ (S/390 debug feature) 30 + The S/390 debug feature (s390dbf) generates views to hold various debug results in sysfs directories of the form: 31 31 32 - Some views generated by the debug feature to hold various debug outputs. 32 + * /sys/kernel/debug/s390dbf/pci_*/ 33 + 34 + For example: 33 35 34 36 - /sys/kernel/debug/s390dbf/pci_msg/sprintf 35 - Messages from the processing of PCI events like machine check handling 36 - and setting of global functionality like UID checking. 37 + Holds messages from the processing of PCI events, like machine check handling 38 + and setting of global functionality, like UID checking. 37 39 38 - The level of logging can be changed to be more or less verbose by piping to 39 - /sys/kernel/debug/s390dbf/pci_*/level a number between 0 and 6; see the 40 - documentation on the S/390 debug feature (Documentation/s390/s390dbf.rst) 41 - for details. 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. 42 44 43 45 Sysfs entries 44 46 ============= 45 47 46 - Specific entries, or entries specificities for zPCI functions. 48 + Entries specific to zPCI functions and entries that hold zPCI information. 47 49 48 50 * /sys/bus/pci/slots/XXXXXXXX 49 51 50 - The slot entries are setup using the FID (Function Identifier) of the 52 + The slot entries are set up using the function identifier (FID) of the 51 53 PCI function. 52 54 53 55 - /sys/bus/pci/slots/XXXXXXXX/power 54 56 55 - A physical function currently supporting virtual function can not be 56 - powered-off until all virtual-function have been removed with 57 + A physical function that currently supports a virtual function cannot be 58 + powered off until all virtual functions are removed with: 57 59 echo 0 > /sys/bus/pci/devices/XXXX:XX:XX.X/sriov_numvf 58 60 59 61 * /sys/bus/pci/devices/XXXX:XX:XX.X/ 60 62 61 63 - function_id 62 - zPCI function identifier unique for the complete Z System. 63 - It define uniquely a function in the system. 64 + A zPCI function identifier that uniquely identifies the function in the Z server. 64 65 65 66 - function_handle 66 - Low level identifier used for a configured PCI function. 67 - It may be useful for debuging. 67 + Low-level identifier used for a configured PCI function. 68 + It might be useful for debuging. 68 69 69 70 - pchid 70 - Model dependent location of the I/O adapter. 71 + Model-dependent location of the I/O adapter. 71 72 72 73 - pfgid 73 - PCI Function Group ID, functions sharing identical functionality 74 - are using a common identifier. 75 - A PCI group defines interrupts, IOMMU, IOTLB and DMA specifics. 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. 76 77 77 78 - vfn 78 - The Virtual Function Number, from 1 to N for virtual functions. 79 + The virtual function number, from 1 to N for virtual functions, 79 80 0 for physical functions. 80 81 81 82 - pft 82 - PCI function type specifies the type of the PCI function. 83 + The PCI function type 83 84 84 85 - port 85 - The port correspond to the physical port the function is attached to. 86 - It also gives an indication on the physical function a virtual function 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 87 88 is attached to. 88 89 89 90 - uid 90 - The UID, Unique Identifier is defined when configuring a LPAR and is 91 - unique inside an LPAR. 91 + The unique identifier (UID) is defined when configuring an LPAR and is 92 + unique in the LPAR. 92 93 93 94 - pfip/segmentX 94 - The segments are used to determine the isolation of a function. 95 - They corresponds to the physical path to the function. 96 - The more the segment are different the more the functions are isolated. 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. 97 98 98 99 Enumeration and hotplug 99 100 ======================= 100 101 101 - The PCI address is made of 4 parts: domain, bus, device and function, 102 - like in DDDD:BB:dd.f 102 + The PCI address consists of four parts: domain, bus, device and function, 103 + and is of this form: DDDD:BB:dd.f 103 104 104 - * When not using multi-functions (norid is set or firmware does not support 105 - multi-functions) 105 + * When not using multi-functions (norid is set, or the firmware does not 106 + support multi-functions): 106 107 107 108 - There is only one function per domain. 108 109 109 - - the domain is set from the zPCI function's UID as defined during the 110 + - The domain is set from the zPCI function's UID as defined during the 110 111 LPAR creation. 111 112 112 - - Addresses look like DDDD:00:00.0 113 - 114 - * When using multi-functions (norid parameter is not set), there are some 115 - change in the way zPCI functions are addressed: 113 + * When using multi-functions (norid parameter is not set), 114 + zPCI functions are addressed differently: 116 115 117 116 - There is still only one bus per domain. 118 117 119 118 - There can be up to 256 functions per bus. 120 119 121 - - The domain part of the address of all functions of all functions for 120 + - The domain part of the address of all functions for 122 121 a multi-Function device is set from the zPCI function's UID as defined 123 122 in the LPAR creation for the function zero. 124 123 125 - - New functions will only be ready to be used after the function zero 124 + - New functions will only be ready for use after the function zero 126 125 (the function with devfn 0) has been enumerated.