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