From de267a7c71ba6be7857da0185871759067513d9c Mon Sep 17 00:00:00 2001 From: Pierre Morel Date: Wed, 1 Apr 2020 11:12:24 +0200 Subject: s390/pci: Documentation for zPCI There are changes in the usage of PCI for the user: - new kernel parameter - modification of the way functions are enumerated Let's document these. Signed-off-by: Pierre Morel Signed-off-by: Vasily Gorbik --- Documentation/s390/index.rst | 1 + Documentation/s390/pci.rst | 126 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 127 insertions(+) create mode 100644 Documentation/s390/pci.rst (limited to 'Documentation/s390') diff --git a/Documentation/s390/index.rst b/Documentation/s390/index.rst index f7af2061e406..cf71df5776b4 100644 --- a/Documentation/s390/index.rst +++ b/Documentation/s390/index.rst @@ -15,6 +15,7 @@ s390 Architecture vfio-ccw zfcpdump common_io + pci text_files diff --git a/Documentation/s390/pci.rst b/Documentation/s390/pci.rst new file mode 100644 index 000000000000..75e043d4da85 --- /dev/null +++ b/Documentation/s390/pci.rst @@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========= +S/390 PCI +========= + +Authors: + - Pierre Morel + +Copyright, IBM Corp. 2020 + + +command line parameters and debugfs entries +=========================================== + +Command line parameters +----------------------- + +* nomio + + Do not use MIO instructions. + +* norid + + Ignore the RID field and force use of one PCI domain per PCI function. + +debugfs entries +--------------- + +* /sys/kernel/debug/s390dbf/pci_*/ (S/390 debug feature) + + Some views generated by the debug feature to hold various debug outputs. + + - /sys/kernel/debug/s390dbf/pci_msg/sprintf + Messages from the processing of PCI events like machine check handling + and setting of global functionality like UID checking. + + The level of logging can be changed to be more or less verbose by piping to + /sys/kernel/debug/s390dbf/pci_*/level a number between 0 and 6; see the + documentation on the S/390 debug feature (Documentation/s390/s390dbf.rst) + for details. + +Sysfs entries +============= + +Specific entries, or entries specificities for zPCI functions. + +* /sys/bus/pci/slots/XXXXXXXX + + The slot entries are setup using the FID (Function Identifier) of the + PCI function. + + - /sys/bus/pci/slots/XXXXXXXX/power + + A physical function currently supporting virtual function can not be + powered-off until all virtual-function have been removed with + echo 0 > /sys/bus/pci/devices/XXXX:XX:XX.X/sriov_numvf + +* /sys/bus/pci/devices/XXXX:XX:XX.X/ + + - function_id + zPCI function identifier unique for the complete Z System. + It define uniquely a function in the system. + + - function_handle + Low level identifier used for a configured PCI function. + It may be useful for debuging. + + - pchid + Model dependent location of the I/O adapter. + + - pfgid + PCI Function Group ID, functions sharing identical functionality + are using a common identifier. + A PCI group defines interrupts, IOMMU, IOTLB and DMA specifics. + + - vfn + The Virtual Function Number, from 1 to N for virtual functions. + 0 for physical functions. + + - pft + PCI function type specifies the type of the PCI function. + + - port + The port correspond to the physical port the function is attached to. + It also gives an indication on the physical function a virtual function + is attached to. + + - uid + The UID, Unique Identifier is defined when configuring a LPAR and is + unique inside an LPAR. + + - pfip/segmentX + The segments are used to determine the isolation of a function. + They corresponds to the physical path to the function. + The more the segment are different the more the functions are isolated. + +Enumeration and hotplug +======================= + +The PCI address is made of 4 parts: domain, bus, device and function, +like in DDDD:BB:dd.f + +* When not using multi-functions (norid is set or firmware does not support + multi-functions) + + - There is only one function per domain. + + - the domain is set from the zPCI function's UID as defined during the + LPAR creation. + + - Addresses look like DDDD:00:00.0 + +* When using multi-functions (norid parameter is not set), there are some + change in the way zPCI functions are addressed: + + - There is still only one bus per domain. + + - There can be up to 256 functions per bus. + + - The domain part of the address of all functions of all functions for + a multi-Function device is set from the zPCI function's UID as defined + in the LPAR creation for the function zero. + + - New functions will only be ready to be used after the function zero + (the function with devfn 0) has been enumerated. -- cgit v1.2.3 From 9056754f65052bed370df04523dc3e8628948f9c Mon Sep 17 00:00:00 2001 From: Pierre Morel Date: Thu, 30 Apr 2020 04:02:17 -0400 Subject: s390/pci: Documentation update for s390 PCI Clarify the documentation. Signed-off-by: Pierre Morel Reviewed-by: Niklas Schnelle Signed-off-by: Vasily Gorbik --- Documentation/s390/pci.rst | 83 +++++++++++++++++++++++----------------------- 1 file changed, 41 insertions(+), 42 deletions(-) (limited to 'Documentation/s390') diff --git a/Documentation/s390/pci.rst b/Documentation/s390/pci.rst index 75e043d4da85..492850bff316 100644 --- a/Documentation/s390/pci.rst +++ b/Documentation/s390/pci.rst @@ -10,7 +10,7 @@ Authors: Copyright, IBM Corp. 2020 -command line parameters and debugfs entries +Command line parameters and debugfs entries =========================================== Command line parameters @@ -18,7 +18,7 @@ Command line parameters * nomio - Do not use MIO instructions. + Do not use PCI Mapped I/O (MIO) instructions. * norid @@ -27,100 +27,99 @@ Command line parameters debugfs entries --------------- -* /sys/kernel/debug/s390dbf/pci_*/ (S/390 debug feature) +The S/390 debug feature (s390dbf) generates views to hold various debug results in sysfs directories of the form: - Some views generated by the debug feature to hold various debug outputs. + * /sys/kernel/debug/s390dbf/pci_*/ + +For example: - /sys/kernel/debug/s390dbf/pci_msg/sprintf - Messages from the processing of PCI events like machine check handling - and setting of global functionality like UID checking. + Holds messages from the processing of PCI events, like machine check handling + and setting of global functionality, like UID checking. - The level of logging can be changed to be more or less verbose by piping to - /sys/kernel/debug/s390dbf/pci_*/level a number between 0 and 6; see the - documentation on the S/390 debug feature (Documentation/s390/s390dbf.rst) - for details. + Change the level of logging to be more or less verbose by piping + a number between 0 and 6 to /sys/kernel/debug/s390dbf/pci_*/level. For + details, see the documentation on the S/390 debug feature at + Documentation/s390/s390dbf.rst. Sysfs entries ============= -Specific entries, or entries specificities for zPCI functions. +Entries specific to zPCI functions and entries that hold zPCI information. * /sys/bus/pci/slots/XXXXXXXX - The slot entries are setup using the FID (Function Identifier) of the + The slot entries are set up using the function identifier (FID) of the PCI function. - /sys/bus/pci/slots/XXXXXXXX/power - A physical function currently supporting virtual function can not be - powered-off until all virtual-function have been removed with + A physical function that currently supports a virtual function cannot be + powered off until all virtual functions are removed with: echo 0 > /sys/bus/pci/devices/XXXX:XX:XX.X/sriov_numvf * /sys/bus/pci/devices/XXXX:XX:XX.X/ - function_id - zPCI function identifier unique for the complete Z System. - It define uniquely a function in the system. + A zPCI function identifier that uniquely identifies the function in the Z server. - function_handle - Low level identifier used for a configured PCI function. - It may be useful for debuging. + Low-level identifier used for a configured PCI function. + It might be useful for debuging. - pchid - Model dependent location of the I/O adapter. + Model-dependent location of the I/O adapter. - pfgid - PCI Function Group ID, functions sharing identical functionality - are using a common identifier. - A PCI group defines interrupts, IOMMU, IOTLB and DMA specifics. + PCI function group ID, functions that share identical functionality + use a common identifier. + A PCI group defines interrupts, IOMMU, IOTLB, and DMA specifics. - vfn - The Virtual Function Number, from 1 to N for virtual functions. + The virtual function number, from 1 to N for virtual functions, 0 for physical functions. - pft - PCI function type specifies the type of the PCI function. + The PCI function type - port - The port correspond to the physical port the function is attached to. - It also gives an indication on the physical function a virtual function + The port corresponds to the physical port the function is attached to. + It also gives an indication of the physical function a virtual function is attached to. - uid - The UID, Unique Identifier is defined when configuring a LPAR and is - unique inside an LPAR. + The unique identifier (UID) is defined when configuring an LPAR and is + unique in the LPAR. - pfip/segmentX - The segments are used to determine the isolation of a function. - They corresponds to the physical path to the function. - The more the segment are different the more the functions are isolated. + The segments determine the isolation of a function. + They correspond to the physical path to the function. + The more the segments are different, the more the functions are isolated. Enumeration and hotplug ======================= -The PCI address is made of 4 parts: domain, bus, device and function, -like in DDDD:BB:dd.f +The PCI address consists of four parts: domain, bus, device and function, +and is of this form: DDDD:BB:dd.f -* When not using multi-functions (norid is set or firmware does not support - multi-functions) +* When not using multi-functions (norid is set, or the firmware does not + support multi-functions): - There is only one function per domain. - - the domain is set from the zPCI function's UID as defined during the + - The domain is set from the zPCI function's UID as defined during the LPAR creation. - - Addresses look like DDDD:00:00.0 - -* When using multi-functions (norid parameter is not set), there are some - change in the way zPCI functions are addressed: +* When using multi-functions (norid parameter is not set), + zPCI functions are addressed differently: - There is still only one bus per domain. - There can be up to 256 functions per bus. - - The domain part of the address of all functions of all functions for + - The domain part of the address of all functions for a multi-Function device is set from the zPCI function's UID as defined in the LPAR creation for the function zero. - - New functions will only be ready to be used after the function zero + - New functions will only be ready for use after the function zero (the function with devfn 0) has been enumerated. -- cgit v1.2.3 From d03756aa0535f347f321c681ab0ca0fc7ba335bc Mon Sep 17 00:00:00 2001 From: Gerald Schaefer Date: Thu, 7 May 2020 16:21:37 +0200 Subject: Documentation/s390: Update / remove developerWorks web links s390 documentation now lives in IBM Knowledge Center, so update the link in the zfcpdump documentation. Also, remove the old developerWorks links from the appldata source code. Those were not really documentation related, but rather a reminder to the developer that some documentation has to be adjusted when changing the record layout, which should still be pretty obvious from the remaining comment. Signed-off-by: Gerald Schaefer Signed-off-by: Vasily Gorbik --- Documentation/s390/zfcpdump.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/s390') diff --git a/Documentation/s390/zfcpdump.rst b/Documentation/s390/zfcpdump.rst index 54e8e7caf7e7..a61de7aa8778 100644 --- a/Documentation/s390/zfcpdump.rst +++ b/Documentation/s390/zfcpdump.rst @@ -46,5 +46,5 @@ initramfs with a user space application that writes the dump to a SCSI partition. For more information on how to use zfcpdump refer to the s390 'Using the Dump -Tools book', which is available from -http://www.ibm.com/developerworks/linux/linux390. +Tools' book, which is available from IBM Knowledge Center: +https://www.ibm.com/support/knowledgecenter/linuxonibm/liaaf/lnz_r_dt.html -- cgit v1.2.3 From 725b94d74128cd208bfdd446ad6b5f4b38cf5395 Mon Sep 17 00:00:00 2001 From: Jared Rossi Date: Wed, 6 May 2020 17:24:40 -0400 Subject: vfio-ccw: Enable transparent CCW IPL from DASD Remove the explicit prefetch check when using vfio-ccw devices. This check does not trigger in practice as all Linux channel programs are intended to use prefetch. It is expected that all ORBs issued by Linux will request prefetch. Although non-prefetching ORBs are not rejected, they will prefetch nonetheless. A warning is issued up to once per 5 seconds when a forced prefetch occurs. A non-prefetch ORB does not necessarily result in an error, however frequent encounters with non-prefetch ORBs indicate that channel programs are being executed in a way that is inconsistent with what the guest is requesting. While there is currently no known case of an error caused by forced prefetch, it is possible in theory that forced prefetch could result in an error if applied to a channel program that is dependent on non-prefetch. Signed-off-by: Jared Rossi Reviewed-by: Eric Farman Message-Id: <20200506212440.31323-2-jrossi@linux.ibm.com> Signed-off-by: Cornelia Huck --- Documentation/s390/vfio-ccw.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation/s390') diff --git a/Documentation/s390/vfio-ccw.rst b/Documentation/s390/vfio-ccw.rst index fca9c4f5bd9c..23e7d136f8b4 100644 --- a/Documentation/s390/vfio-ccw.rst +++ b/Documentation/s390/vfio-ccw.rst @@ -335,6 +335,12 @@ device. The current code allows the guest to start channel programs via START SUBCHANNEL, and to issue HALT SUBCHANNEL and CLEAR SUBCHANNEL. +Currently all channel programs are prefetched, regardless of the +p-bit setting in the ORB. As a result, self modifying channel +programs are not supported. For this reason, IPL has to be handled as +a special case by a userspace/guest program; this has been implemented +in QEMU's s390-ccw bios as of QEMU 4.1. + vfio-ccw supports classic (command mode) channel I/O only. Transport mode (HPF) is not supported. -- cgit v1.2.3 From 430220b0bbcbaaaa03718111ff541ee8cd97c781 Mon Sep 17 00:00:00 2001 From: Cornelia Huck Date: Tue, 7 Apr 2020 13:16:05 +0200 Subject: vfio-ccw: document possible errors Interacting with the I/O and the async regions can yield a number of errors, which had been undocumented so far. These are part of the api, so remedy that. Signed-off-by: Cornelia Huck Reviewed-by: Eric Farman Message-Id: <20200407111605.1795-1-cohuck@redhat.com> --- Documentation/s390/vfio-ccw.rst | 56 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) (limited to 'Documentation/s390') diff --git a/Documentation/s390/vfio-ccw.rst b/Documentation/s390/vfio-ccw.rst index 23e7d136f8b4..3a946fd45562 100644 --- a/Documentation/s390/vfio-ccw.rst +++ b/Documentation/s390/vfio-ccw.rst @@ -204,15 +204,44 @@ definition of the region is:: __u32 ret_code; } __packed; +This region is always available. + While starting an I/O request, orb_area should be filled with the guest ORB, and scsw_area should be filled with the SCSW of the Virtual Subchannel. irb_area stores the I/O result. -ret_code stores a return code for each access of the region. +ret_code stores a return code for each access of the region. The following +values may occur: + +``0`` + The operation was successful. + +``-EOPNOTSUPP`` + The orb specified transport mode or an unidentified IDAW format, or the + scsw specified a function other than the start function. + +``-EIO`` + A request was issued while the device was not in a state ready to accept + requests, or an internal error occurred. + +``-EBUSY`` + The subchannel was status pending or busy, or a request is already active. + +``-EAGAIN`` + A request was being processed, and the caller should retry. + +``-EACCES`` + The channel path(s) used for the I/O were found to be not operational. + +``-ENODEV`` + The device was found to be not operational. + +``-EINVAL`` + The orb specified a chain longer than 255 ccws, or an internal error + occurred. -This region is always available. vfio-ccw cmd region ------------------- @@ -231,6 +260,29 @@ This region is exposed via region type VFIO_REGION_SUBTYPE_CCW_ASYNC_CMD. Currently, CLEAR SUBCHANNEL and HALT SUBCHANNEL use this region. +command specifies the command to be issued; ret_code stores a return code +for each access of the region. The following values may occur: + +``0`` + The operation was successful. + +``-ENODEV`` + The device was found to be not operational. + +``-EINVAL`` + A command other than halt or clear was specified. + +``-EIO`` + A request was issued while the device was not in a state ready to accept + requests. + +``-EAGAIN`` + A request was being processed, and the caller should retry. + +``-EBUSY`` + The subchannel was status pending or busy while processing a halt request. + + vfio-ccw operation details -------------------------- -- cgit v1.2.3 From 24c986748ba670c903a9d6a11ee96de2b3f5f1b8 Mon Sep 17 00:00:00 2001 From: Farhan Ali Date: Tue, 5 May 2020 14:27:41 +0200 Subject: vfio-ccw: Introduce a new schib region The schib region can be used by userspace to get the subchannel- information block (SCHIB) for the passthrough subchannel. This can be useful to get information such as channel path information via the SCHIB.PMCW fields. Signed-off-by: Farhan Ali Signed-off-by: Eric Farman Reviewed-by: Cornelia Huck Message-Id: <20200505122745.53208-5-farman@linux.ibm.com> Signed-off-by: Cornelia Huck --- Documentation/s390/vfio-ccw.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'Documentation/s390') diff --git a/Documentation/s390/vfio-ccw.rst b/Documentation/s390/vfio-ccw.rst index 3a946fd45562..32310df525ba 100644 --- a/Documentation/s390/vfio-ccw.rst +++ b/Documentation/s390/vfio-ccw.rst @@ -282,6 +282,21 @@ for each access of the region. The following values may occur: ``-EBUSY`` The subchannel was status pending or busy while processing a halt request. +vfio-ccw schib region +--------------------- + +The vfio-ccw schib region is used to return Subchannel-Information +Block (SCHIB) data to userspace:: + + struct ccw_schib_region { + #define SCHIB_AREA_SIZE 52 + __u8 schib_area[SCHIB_AREA_SIZE]; + } __packed; + +This region is exposed via region type VFIO_REGION_SUBTYPE_CCW_SCHIB. + +Reading this region triggers a STORE SUBCHANNEL to be issued to the +associated hardware. vfio-ccw operation details -------------------------- @@ -385,7 +400,8 @@ through DASD/ECKD device online in a guest now and use it as a block device. The current code allows the guest to start channel programs via -START SUBCHANNEL, and to issue HALT SUBCHANNEL and CLEAR SUBCHANNEL. +START SUBCHANNEL, and to issue HALT SUBCHANNEL, CLEAR SUBCHANNEL, +and STORE SUBCHANNEL. Currently all channel programs are prefetched, regardless of the p-bit setting in the ORB. As a result, self modifying channel -- cgit v1.2.3 From d8cac29b1d52204e6632d2887eff766acd02b9aa Mon Sep 17 00:00:00 2001 From: Farhan Ali Date: Tue, 5 May 2020 14:27:43 +0200 Subject: vfio-ccw: Introduce a new CRW region This region provides a mechanism to pass a Channel Report Word that affect vfio-ccw devices, and needs to be passed to the guest for its awareness and/or processing. The base driver (see crw_collect_info()) provides space for two CRWs, as a subchannel event may have two CRWs chained together (one for the ssid, one for the subchannel). As vfio-ccw will deal with everything at the subchannel level, provide space for a single CRW to be transferred in one shot. Signed-off-by: Farhan Ali Signed-off-by: Eric Farman Reviewed-by: Cornelia Huck Message-Id: <20200505122745.53208-7-farman@linux.ibm.com> [CH: added padding to ccw_crw_region] Signed-off-by: Cornelia Huck --- Documentation/s390/vfio-ccw.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'Documentation/s390') diff --git a/Documentation/s390/vfio-ccw.rst b/Documentation/s390/vfio-ccw.rst index 32310df525ba..8aad08a8b8a5 100644 --- a/Documentation/s390/vfio-ccw.rst +++ b/Documentation/s390/vfio-ccw.rst @@ -298,6 +298,26 @@ This region is exposed via region type VFIO_REGION_SUBTYPE_CCW_SCHIB. Reading this region triggers a STORE SUBCHANNEL to be issued to the associated hardware. +vfio-ccw crw region +--------------------- + +The vfio-ccw crw region is used to return Channel Report Word (CRW) +data to userspace:: + + struct ccw_crw_region { + __u32 crw; + __u32 pad; + } __packed; + +This region is exposed via region type VFIO_REGION_SUBTYPE_CCW_CRW. + +Reading this region returns a CRW if one that is relevant for this +subchannel (e.g. one reporting changes in channel path state) is +pending, or all zeroes if not. If multiple CRWs are pending (including +possibly chained CRWs), reading this region again will return the next +one, until no more CRWs are pending and zeroes are returned. This is +similar to how STORE CHANNEL REPORT WORD works. + vfio-ccw operation details -------------------------- -- cgit v1.2.3