1PCI Slots 2========= 3 4The PCI slots are instantiated to represent their associated properties and 5operations. The slot properties are exported to OS through the device tree 6node of the corresponding parent PCI device. The slot operations are used 7to accomodate requests from OS regarding the indicated PCI slot: 8 9 * PCI slot reset 10 * PCI slot property retrival 11 12The PCI slots are expected to be created by individual platforms based on 13the given templates, which are classified to PHB slot or normal one currently. 14The PHB slot is instantiated based on PHB types like P7IOC and PHB3. However, 15the normal PCI slots are created based on general RC (Root Complex), PCIE switch 16ports, PCIE-to-PCIx bridge. Individual platform may create PCI slot, which doesn't 17have existing template. 18 19The PCI slots are created at different stages according to their types. PHB slots 20are expected to be created once the PHB is register (struct platform::pci_setup_phb()) 21because the PHB slot reset operations are required at early stage of PCI enumeration. 22The normal slots are populated after their parent PCI devices are instantiated at 23struct platform::pci_get_slot_info(). 24 25The operation set supplied by the template might be overrided and reimplemented, or 26partially. It's usually done according to the VPD figured out by individual platforms. 27 28PCI Slot Operations 29------------------- 30 31The following operations are supported to one particular PCI slot. More details 32could be found from the definition of struct pci_slot_ops: 33 34===================== ========== 35Operation Definition 36===================== ========== 37get_presence_state Check if any adapter connected to slot 38get_link_state Retrieve PCIE link status: up, down, link width 39get_power_state Retrieve the power status: on, off 40get_attention_state Retrieve attention status: on, off, blinking 41get_latch_state Retrieve latch status 42set_power_state Configure the power status: on, off 43set_attention_state Configure attention status: on, off, blinking 44 45prepare_link_change Prepare PCIE link status change 46poll_link Poll PCIE link until it's up or down permanently 47creset Complete reset, only available to PHB slot 48freset Fundamental reset 49hreset Hot reset 50poll Interface for OPAL API to drive internal state machine 51 52add_properties Additional PCI slot properties seen by platform 53===================== ========== 54 55PCI Slot Properties 56=================== 57 58The following PCI slot properties have been exported through PCI device tree 59node for a root port, a PCIE switch port, or a PCIE to PCIx bridge. If the 60individual platforms (e.g. Firenze and Apollo) have VPD for the PCI slot, they 61should extract the PCI slot properties from VPD and export them accordingly. 62 63=========================== ========== 64Property Definition 65=========================== ========== 66ibm,reset-by-firmware Boolean indicating whether the slot reset should be done in firmware 67ibm,slot-pluggable Boolean indicating whether the slot is pluggable 68ibm,slot-surprise-pluggable Boolean indicating whether the slot supports surprise hotplug 69ibm,slot-broken-pdc Boolean indicating whether PDC (Presence Detection Change) is broken 70ibm,slot-power-ctl Boolean indicating whether the slot has power control 71ibm,slot-wired-lanes The number of hardware lanes that are wired 72ibm,slot-pwr-led-ctl Presence of slot power led, and controlling entity 73ibm,slot-attn-led-ctl Presence of slot ATTN led, and controlling entity 74=========================== ========== 75 76PCI Hotplug 77----------- 78 79The implementation of PCI slot hotplug heavily relies on its power state. 80Initially, the slot is powered off if there are no adapters behind it. 81Otherwise, the slot should be powered on. 82 83In hot add scenario, the adapter is physically inserted to PCI slot. Then 84the PCI slot is powered on by OPAL API opal_pci_set_power_state(). The 85power is supplied to the PCI slot, the adapter behind the PCI slot is 86probed and the device sub-tree (for hot added devices) is populated. A 87OPAL message is sent to OS on completion. The OS needs retrieve the device 88sub-tree through OPAL API opal_get_device_tree(), unflatten it and populate 89the device sub-tree. After that, the adapter behind the PCI slot should 90be probed and added to the system. 91 92On the other hand, the OS removes the adapter behind the PCI slot before 93calling opal_pci_set_power_state(). Skiboot cuts off the power supply to 94the PCI slot, removes the adapter behind the PCI slot and the corresponding 95device sub-tree. A OPAL message (OPAL_MSG_ASYNC_COMP) is sent to OS. The 96OS removes the device sub-tree for the adapter behind the PCI slot. 97 98The OPAL message used in PCI hotplug is comprised of 4 dwords in sequence: 99asychronous token from OS, PCI slot device node's phandle, OPAL_PCI_SLOT_POWER_{ON, 100OFF}, OPAL_SUCCESS or errcode. 101 102The states OPAL_PCI_SLOT_OFFLINE and OPAL_PCI_SLOT_ONLINE are used for removing 103or adding devices behind the slot. The device nodes in the device tree are 104removed or added accordingly, without actually changing the slot's power state. 105The API call will return OPAL_SUCCESS immediately and no further asynchronous 106message will be sent. 107 108PCI Slot on Apollo and Firenze 109------------------------------ 110 111On IBM's Apollo and Firenze platform, the PCI VPD is fetched from dedicated LID, 112which is organized in so-called 1004, 1005, or 1006 format. 1006 mapping format 113isn't supported currently. The PCI slot properties are figured out from the VPD. 114On the other hand, there might have external power management entity hooked to 115I2C buses for one PCI slot. The fundamental reset operation of the PCI slot should 116be implemented based on the external power management entity for that case. 117 118On Firenze platform, PERST pin is accessible through bit#10 of PCI config register 119(offset: 0x80) for those PCI slots behind some PLX switch downstream ports. For 120those PCI slots, PERST pin is utilized to implement fundamental reset if external 121power management entity doesn't exist. 122 123For Apollo and Firenze platform, following PCI slot properties are exported through 124PCI device tree node except those generic properties (as above): 125 126======================= ========== 127Property Definition 128======================= ========== 129ibm,slot-location-code System location code string for the slot connector 130ibm,slot-label Slot label, part of "ibm,slot-location-code" 131======================= ========== 132