From patchwork Fri Jun 10 05:03:52 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gavin Shan X-Patchwork-Id: 633523 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3rQqvC1DKDz9sD3 for ; Fri, 10 Jun 2016 15:08:23 +1000 (AEST) Received: from ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 3rQqvC0TJDzDqfM for ; Fri, 10 Jun 2016 15:08:23 +1000 (AEST) X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Received: from mx0a-001b2d01.pphosted.com (mx0b-001b2d01.pphosted.com [148.163.158.5]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 3rQqrt5hmdzDqQW for ; Fri, 10 Jun 2016 15:06:22 +1000 (AEST) Received: from pps.filterd (m0049461.ppops.net [127.0.0.1]) by mx0b-001b2d01.pphosted.com (8.16.0.11/8.16.0.11) with SMTP id u5A53rl7013164 for ; Fri, 10 Jun 2016 01:06:20 -0400 Received: from e23smtp03.au.ibm.com (e23smtp03.au.ibm.com [202.81.31.145]) by mx0b-001b2d01.pphosted.com with ESMTP id 23fa5xy89g-1 (version=TLSv1.2 cipher=AES256-SHA bits=256 verify=NOT) for ; Fri, 10 Jun 2016 01:06:20 -0400 Received: from localhost by e23smtp03.au.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Fri, 10 Jun 2016 15:06:16 +1000 Received: from d23dlp03.au.ibm.com (202.81.31.214) by e23smtp03.au.ibm.com (202.81.31.209) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Fri, 10 Jun 2016 15:06:14 +1000 X-IBM-Helo: d23dlp03.au.ibm.com X-IBM-MailFrom: gwshan@linux.vnet.ibm.com X-IBM-RcptTo: skiboot@lists.ozlabs.org Received: from d23relay06.au.ibm.com (d23relay06.au.ibm.com [9.185.63.219]) by d23dlp03.au.ibm.com (Postfix) with ESMTP id BFF743578052 for ; Fri, 10 Jun 2016 15:06:03 +1000 (EST) Received: from d23av04.au.ibm.com (d23av04.au.ibm.com [9.190.235.139]) by d23relay06.au.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id u5A55h108323398 for ; Fri, 10 Jun 2016 15:05:43 +1000 Received: from d23av04.au.ibm.com (localhost [127.0.0.1]) by d23av04.au.ibm.com (8.14.4/8.14.4/NCO v10.0 AVout) with ESMTP id u5A55M6j026235 for ; Fri, 10 Jun 2016 15:05:22 +1000 Received: from ozlabs.au.ibm.com (ozlabs.au.ibm.com [9.192.253.14]) by d23av04.au.ibm.com (8.14.4/8.14.4/NCO v10.0 AVin) with ESMTP id u5A55LAw025856; Fri, 10 Jun 2016 15:05:22 +1000 Received: from bran.ozlabs.ibm.com (haven.au.ibm.com [9.192.254.114]) by ozlabs.au.ibm.com (Postfix) with ESMTP id 4BC72A039A; Fri, 10 Jun 2016 15:04:00 +1000 (AEST) Received: from gwshan (shangw.ozlabs.ibm.com [10.61.2.199]) by bran.ozlabs.ibm.com (Postfix) with ESMTP id 4A44EE3B17; Fri, 10 Jun 2016 15:04:00 +1000 (AEST) Received: by gwshan (Postfix, from userid 1000) id 2E461942CA3; Fri, 10 Jun 2016 15:04:00 +1000 (AEST) From: Gavin Shan To: skiboot@lists.ozlabs.org Date: Fri, 10 Jun 2016 15:03:52 +1000 X-Mailer: git-send-email 2.1.0 In-Reply-To: <1465535032-26749-1-git-send-email-gwshan@linux.vnet.ibm.com> References: <1465535032-26749-1-git-send-email-gwshan@linux.vnet.ibm.com> X-TM-AS-MML: disable X-Content-Scanned: Fidelis XPS MAILER x-cbid: 16061005-0008-0000-0000-000000971711 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 16061005-0009-0000-0000-0000076DBDE1 Message-Id: <1465535032-26749-24-git-send-email-gwshan@linux.vnet.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:, , definitions=2016-06-10_04:, , signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 spamscore=0 suspectscore=1 malwarescore=0 phishscore=0 adultscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1604210000 definitions=main-1606100058 Subject: [Skiboot] [PATCH v12 23/23] doc: PCI slot X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: Mailing list for skiboot development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: alistair@popple.id.au MIME-Version: 1.0 Errors-To: skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Skiboot" This renames document pci-slot-properties.txt to pci-slot.txt and more description added regarding the new introduced functionalities to PCI slot by the series of patches. Signed-off-by: Gavin Shan --- doc/pci-slot-properties.txt | 17 ------- doc/pci-slot.txt | 119 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+), 17 deletions(-) delete mode 100644 doc/pci-slot-properties.txt create mode 100644 doc/pci-slot.txt diff --git a/doc/pci-slot-properties.txt b/doc/pci-slot-properties.txt deleted file mode 100644 index 2ee34ea..0000000 --- a/doc/pci-slot-properties.txt +++ /dev/null @@ -1,17 +0,0 @@ - -PCI Slot Properties Description -=============================== - -The following properties have been added to the PCI Device Tree Node -for the PCI Slot: - -ibm,slot-location-code System location code string for the slot connector -ibm,slot-pluggable Boolean indicating whether the slot is pluggable -ibm,slot-power-ctl Boolean indicating whether the slot has power control -ibm,slot-wired-lanes The number of hardware lanes that are wired (optional) -ibm,slot-connector-type The type of connector present (optional) -ibm,slot-card-desc The height/length of the slot (optional) -ibm,slot-card-mech Value indicating slot mechanicals and orientation (optional) -ibm,slot-pwr-led-ctl Presence of slot power led, and controlling entity (optional) -ibm,slot-attn-led-ctl Presence of slot ATTN led, and controlling entity (optional) - diff --git a/doc/pci-slot.txt b/doc/pci-slot.txt new file mode 100644 index 0000000..1b64f69 --- /dev/null +++ b/doc/pci-slot.txt @@ -0,0 +1,119 @@ +Overview +======== + +The PCI slots are instantiated to represent their associated properties and +operations. The slot properties are exported to OS through the device tree +node of the corresponding parent PCI device. The slot operations are used +to accomodate requests from OS regarding the indicated PCI slot: + + * PCI slot reset + * PCI slot property retrival + +The PCI slots are expected to be created by individual platforms based on +the given templates, which are classified to PHB slot or normal one currently. +The PHB slot is instantiated based on PHB types like P7IOC and PHB3. However, +the normal PCI slots are created based on general RC (Root Complex), PCIE switch +ports, PCIE-to-PCIx bridge. Individual platform may create PCI slot, which doesn't +have existing template. + +The PCI slots are created at different stages according to their types. PHB slots +are expected to be created once the PHB is register (struct platform::pci_setup_phb()) +because the PHB slot reset operations are required at early stage of PCI enumeration. +The normal slots are populated after their parent PCI devices are instantiated at +struct platform::pci_get_slot_info(). + +The operation set supplied by the template might be overrided and reimplemented, or +partially. It's usually done according to the VPD figured out by individual platforms. + +PCI Slot Operations +=================== + +The following operations are supported to one particular PCI slot. More details +could be found from the definition of struct pci_slot_ops: + +get_presence_state Check if any adapter connected to slot +get_link_state Retrieve PCIE link status: up, down, link width +get_power_state Retrieve the power status: on, off +get_attention_state Retrieve attention status: on, off, blinking +get_latch_state Retrieve latch status +set_power_state Configure the power status: on, off +set_attention_state Configure attention status: on, off, blinking + +prepare_link_change Prepare PCIE link status change +poll_link Poll PCIE link until it's up or down permanently +creset Complete reset, only available to PHB slot +freset Fundamental reset +pfreset Post fundamental reset +hreset Hot reset +poll Interface for OPAL API to drive internal state machine + +add_properties Additional PCI slot properties seen by platform + +PCI Slot Properties +=================== + +The following PCI slot properties have been exported through PCI device tree +node for a root port, a PCIE switch port, or a PCIE to PCIx bridge. If the +individual platforms (e.g. Firenze and Apollo) have VPD for the PCI slot, they +should extract the PCI slot properties from VPD and export them accordingly. + +ibm,reset-by-firmware Boolean indicating whether the slot reset should be + done in firmware +ibm,slot-pluggable Boolean indicating whether the slot is pluggable +ibm,slot-power-ctl Boolean indicating whether the slot has power control +ibm,slot-wired-lanes The number of hardware lanes that are wired +ibm,slot-pwr-led-ctl Presence of slot power led, and controlling entity +ibm,slot-attn-led-ctl Presence of slot ATTN led, and controlling entity + +PCI Hotplug +=========== + +The implementation of PCI slot hotplug heavily relies on its power state. +Initially, the slot is powered off if there are no adapters behind it. +Otherwise, the slot should be powered on. + +In hot add scenario, the adapter is physically inserted to PCI slot. Then +the PCI slot is powered on by OPAL API opal_pci_set_power_state(). The +power is supplied to the PCI slot, the adapter behind the PCI slot is +probed and the device sub-tree (for hot added devices) is populated. A +OPAL message is sent to OS on completion. The OS needs retrieve the device +sub-tree through OPAL API opal_get_device_tree(), unflatten it and populate +the device sub-tree. After that, the adapter behind the PCI slot should +be probed and added to the system. + +On the other hand, the OS removes the adapter behind the PCI slot before +calling opal_pci_set_power_state(). Skiboot cuts off the power supply to +the PCI slot, removes the adapter behind the PCI slot and the corresponding +device sub-tree. A OPAL message (OPAL_MSG_ASYNC_COMP) is sent to OS. The +OS removes the device sub-tree for the adapter behind the PCI slot. + +The OPAL message used in PCI hotplug is comprised of 4 dwords in sequence: +asychronous token from OS, PCI slot device node's phandle, OPAL_PCI_SLOT_POWER_{ON, +OFF}, OPAL_SUCCESS or errcode. + +The states OPAL_PCI_SLOT_OFFLINE and OPAL_PCI_SLOT_ONLINE are used for removing +or adding devices behind the slot. The device nodes in the device tree are +removed or added accordingly, without actually changing the slot's power state. +The API call will return OPAL_SUCCESS immediately and no further asynchronous +message will be sent. + +PCI Slot on Apollo and Firenze +============================== + +On IBM's Apollo and Firenze platform, the PCI VPD is fetched from dedicated LID, +which is organized in so-called 1004, 1005, or 1006 format. 1006 mapping format +isn't supported currently. The PCI slot properties are figured out from the VPD. +On the other hand, there might have external power management entity hooked to +I2C buses for one PCI slot. The fundamental reset operation of the PCI slot should +be implemented based on the external power management entity for that case. + +On Firenze platform, PERST pin is accessible through bit#10 of PCI config register +(offset: 0x80) for those PCI slots behind some PLX switch downstream ports. For +those PCI slots, PERST pin is utilized to implement fundamental reset if external +power management entity doesn't exist. + +For Apollo and Firenze platform, following PCI slot properties are exported through +PCI device tree node except those generic properties (as above): + +ibm,slot-location-code System location code string for the slot connector +ibm,slot-label Slot label, part of "ibm,slot-location-code"