| PCI Slots |
| ========= |
| |
| 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: |
| |
| ===================== ========== |
| Operation Definition |
| ===================== ========== |
| 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 |
| 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. |
| |
| =========================== ========== |
| Property Definition |
| =========================== ========== |
| 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-surprise-pluggable Boolean indicating whether the slot supports surprise hotplug |
| ibm,slot-broken-pdc Boolean indicating whether PDC (Presence Detection Change) is broken |
| 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): |
| |
| ======================= ========== |
| Property Definition |
| ======================= ========== |
| ibm,slot-location-code System location code string for the slot connector |
| ibm,slot-label Slot label, part of "ibm,slot-location-code" |
| ======================= ========== |
