From patchwork Mon Apr 27 06:26:33 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gavin Shan X-Patchwork-Id: 464805 X-Patchwork-Delegate: benh@kernel.crashing.org Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [103.22.144.68]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id A3B08140082 for ; Mon, 27 Apr 2015 16:28:01 +1000 (AEST) Received: from ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 89B461A0BE1 for ; Mon, 27 Apr 2015 16:28:01 +1000 (AEST) X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Received: from e23smtp07.au.ibm.com (e23smtp07.au.ibm.com [202.81.31.140]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id E02FD1A0BE7 for ; Mon, 27 Apr 2015 16:27:57 +1000 (AEST) Received: from /spool/local by e23smtp07.au.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Mon, 27 Apr 2015 16:27:57 +1000 Received: from d23dlp02.au.ibm.com (202.81.31.213) by e23smtp07.au.ibm.com (202.81.31.204) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Mon, 27 Apr 2015 16:27:56 +1000 Received: from d23relay06.au.ibm.com (d23relay06.au.ibm.com [9.185.63.219]) by d23dlp02.au.ibm.com (Postfix) with ESMTP id 2162A2BB0051 for ; Mon, 27 Apr 2015 16:27:56 +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 t3R6RmYl52166898 for ; Mon, 27 Apr 2015 16:27:56 +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 t3R6RMLu026829 for ; Mon, 27 Apr 2015 16:27: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 t3R6RMr7026328; Mon, 27 Apr 2015 16:27:22 +1000 Received: from bran.ozlabs.ibm.com (haven.au.ibm.com [9.192.253.15]) by ozlabs.au.ibm.com (Postfix) with ESMTP id 27F46A03E6; Mon, 27 Apr 2015 16:26:43 +1000 (AEST) Received: from gwshan (shangw.ozlabs.ibm.com [10.61.2.199]) by bran.ozlabs.ibm.com (Postfix) with ESMTP id EFF1B16AA08; Mon, 27 Apr 2015 16:26:40 +1000 (AEST) Received: by gwshan (Postfix, from userid 1000) id 69099942237; Mon, 27 Apr 2015 16:26:40 +1000 (AEST) From: Gavin Shan To: skiboot@lists.ozlabs.org Date: Mon, 27 Apr 2015 16:26:33 +1000 Message-Id: <1430115993-20560-16-git-send-email-gwshan@linux.vnet.ibm.com> X-Mailer: git-send-email 2.1.0 In-Reply-To: <1430115993-20560-1-git-send-email-gwshan@linux.vnet.ibm.com> References: <1430115993-20560-1-git-send-email-gwshan@linux.vnet.ibm.com> X-TM-AS-MML: disable X-Content-Scanned: Fidelis XPS MAILER x-cbid: 15042706-0025-0000-0000-00000164FB77 Subject: [Skiboot] [PATCH v5 15/15] doc: PCI slot X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Mailing list for skiboot development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Skiboot" The patch renames document pci-slot-properties.txt to pci-slot.txt to include more description about PCI slot there. Signed-off-by: Gavin Shan --- doc/pci-slot-properties.txt | 17 --------- doc/pci-slot.txt | 87 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 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 7aeac3f..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 -ibm,slot-connector-type The type of connector present -ibm,slot-card-desc The height/length of the slot -ibm,slot-card-mech Value indicating slot mechanicals and orientation -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 - diff --git a/doc/pci-slot.txt b/doc/pci-slot.txt new file mode 100644 index 0000000..0765d88 --- /dev/null +++ b/doc/pci-slot.txt @@ -0,0 +1,87 @@ +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_status Check if any adapter connected to slot +get_link_status Retrieve PCIE link status: up, down, link width +get_power_status Retrieve the power status: on, off +get_attention_status Retrieve attention status: on, off, blinking +get_latch_status Retrieve latch status +set_power_status Configure the power status: on, off +set_attention_status 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 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"