1.. SPDX-License-Identifier: GPL-2.0 2 3=================================== 4Writing PCI Host Controller Drivers 5=================================== 6 7:Author: Manivannan Sadhasivam <manivannan.sadhasivam@oss.qualcomm.com> 8 9Introduction 10============ 11 12A PCI Host Controller driver controls PCI Root Complex (RC) hardware. The 13Root Complex hardware comprises a single PCI Host Bridge and one or more 14Root Port or Root Complex Integrated Endpoint (RCiEP) devices:: 15 16 +------------------+ 17 | CPU | 18 +------------------+ 19 | 20 +--------------------------------------------+ 21 | | Root | 22 | +------------------+ Complex | 23 | | Host Bridge | | 24 | +------------------+ | 25 | | | 26 | Bus 0 | | 27 | +------------|----------+ | 28 | | | | | 29 | +----------+ +----------+ +-------+ | 30 | | Root | | Root | | RCiEP | | 31 | | Port | | Port | +-------+ | 32 | +----------+ +----------+ | 33 | | | | 34 | Bus 1 | Bus 2 | | 35 | | | | 36 +-------|-------------|----------------------+ 37 | | 38 +-----------+ +-----------+ 39 | Endpoint | | Endpoint | 40 +-----------+ +-----------+ 41 42Host Bridge: Used to connect CPU(s) to the PCI hierarchy. 43 44Root Port: Virtual PCI-PCI bridge connecting the Host Bridge to a PCI bus. 45 46RCiEP: Embedded PCIe Endpoint inside Root Complex connected to the Host 47Bridge. 48 49Endpoint: PCIe device connected to a Root Port through a Link. 50 51Enumeration 52=========== 53 54The Host Bridge device is not discoverable, so it is typically enumerated 55with the help of firmware interfaces like ACPI or Devicetree. But the Root 56Port and RCiEP devices are discoverable through the standard enumeration 57process defined in the PCIe spec. 58 59A Host Controller driver usually configures both Host Bridge and Root 60Port(s) based on platform requirements. In the case of ACPI on standardized 61platforms (e.g. x86), no platform-specific host controller driver is 62required as the firmware configures the Root Complex before OS boot and 63exposes the resource information through ACPI tables. For more info, refer 64to :doc:`../acpi-info`. 65 66For Devicetree platforms, a dedicated host controller driver is often 67required because the Root Complex hardware typically needs vendor-specific 68initialization like PHY, clocks, power domains, and there is no standard 69mechanism equivalent to ACPI/MCFG to convey resource information to the OS. 70So on these platforms, Root Complex hardware is enumerated through 71Devicetree nodes as below:: 72 73 pcie@10000000 { 74 compatible = "vendor,soc-pcie"; 75 reg = <0x0 0x10000000 0x0 0x1000>, 76 <0x0 0x10001000 0x0 0x1000>; 77 reg-names = "cfg", "app"; 78 device_type = "pci"; 79 bus-range = <0x00 0xff>; 80 linux,pci-domain = <0>; 81 num-lanes = <4>; 82 83 #address-cells = <3>; 84 #size-cells = <2>; 85 86 ranges = <0x01000000 0x0 0x00000000 0x0 0x20000000 0x0 0x00100000>, 87 <0x02000000 0x0 0x20100000 0x0 0x20100000 0x0 0x1ff00000>; 88 dma-ranges = <0x02000000 0x0 0x0 0x0 0x0 0x0 0x80000000>; 89 90 clocks = <&clkc PCIE_CORE_CLK>, 91 <&clkc PCIE_AUX_CLK>; 92 clock-names = "core", "aux"; 93 resets = <&reset PCIE_RESET>; 94 power-domains = <&power PCIE_PD>; 95 96 #interrupt-cells = <1>; 97 interrupt-map-mask = <0 0 0 0x7>; 98 interrupt-map = <0 0 0 1 &gic 0 0 GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>, 99 <0 0 0 2 &gic 0 0 GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>, 100 <0 0 0 3 &gic 0 0 GIC_SPI 102 IRQ_TYPE_LEVEL_HIGH>, 101 <0 0 0 4 &gic 0 0 GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>; 102 interrupts = <GIC_SPI 104 IRQ_TYPE_LEVEL_HIGH>; 103 interrupt-names = "msi"; 104 105 pcie@0 { 106 compatible = "pciclass,0604"; 107 device_type = "pci"; 108 reg = <0x0 0x0 0x0 0x0 0x0>; 109 bus-range = <0x01 0xff>; 110 111 #address-cells = <3>; 112 #size-cells = <2>; 113 ranges; 114 115 phys = <&pcie_phy>; 116 reset-gpios = <&gpio 10 GPIO_ACTIVE_LOW>; 117 wake-gpios = <&gpio 11 GPIO_ACTIVE_LOW>; 118 }; 119 }; 120 121 122Note the presence of two nodes in the above example. The ``pcie@10000000`` 123node represents a PCI Host Bridge device, and ``pcie@0`` represents a 124single Root Port device. The Host Bridge node should contain properties 125associated with the Host Bridge device such as ranges, interrupts, clocks, 126power-domains etc... and the Root Port node should contain port-specific 127properties such as phys, reset-gpios, wake-gpios etc... 128 129NOTE: Legacy Devicetrees used a single node to describe both Host Bridge 130and Root Port devices, but that design is now deprecated. 131 132Driver Design 133============= 134 135Prerequisites 136------------- 137 138Before starting to write a new Host Controller driver, check if any of the 139existing drivers can be reused. For example, if the Root Complex supports 140the Enhanced Configuration Access Mechanism (ECAM) and the bootloader has 141configured the ECAM mapping before OS boot, the ``CONFIG_PCI_HOST_GENERIC`` 142driver can be used. 143 144If the Root Complex hardware (IP) is from IP vendors such as Synopsys or 145Cadence, the existing ``CONFIG_PCIE_DW_PLAT_HOST`` and 146``CONFIG_PCIE_CADENCE_PLAT_HOST`` drivers can be reused. If not, then check 147if any of the existing glue drivers available for these IPs could be 148reused. 149 150If the Root Complex hardware is designed in-house by the SoC vendor, check 151if there is an existing driver from the vendor for their previous 152generation Root Complex hardware. Often, the existing driver can be 153reused with minimal modifications. 154 155Only if the Root Complex doesn't satisfy above prerequisites should a new 156Host Controller driver be written. 157 158Probe 159----- 160 161During the Host Controller driver probe(), it initializes the Root Complex 162hardware and registers the Host Bridge with the PCI core. The typical steps 163are described below. 164 165Initialize Resources 166~~~~~~~~~~~~~~~~~~~~ 167 168At the start of the probe(), initialize Host Bridge-specific resources such 169as clocks, PHYs, regulators, and resets. These resources are described in 170the Host Bridge Devicetree node and should be brought up before accessing 171the controller hardware. 172 173NOTE: Use the devm_*() managed APIs wherever possible so the resources are 174released automatically on probe failure and on driver detach. 175 176Configuration Space Access 177~~~~~~~~~~~~~~~~~~~~~~~~~~ 178 179The PCI core accesses the Configuration Space of the enumerated devices 180through the callbacks provided by the driver in struct pci_ops. These 181callbacks abstract how the Root Complex generates a Configuration Request 182for a given Bus, Device and Function number. 183 184If the Root Complex supports ECAM, the generic accessors can be reused by 185using pci_ecam_map_bus() along with pci_generic_config_read() and 186pci_generic_config_write(). Such drivers can often be built on top of 187pci_host_common_probe() without providing any custom accessors. 188 189Setup Address Translation 190~~~~~~~~~~~~~~~~~~~~~~~~~ 191 192The Host Bridge translates accesses between the CPU address domain and the 193PCI address domain in both directions: 194 195- Outbound: CPU addresses are translated to PCI bus addresses for the 196 Memory and I/O accesses initiated by the CPU towards the downstream 197 devices. These windows are derived from the ``ranges`` property of the 198 Host Bridge Devicetree node. 199 200- Inbound: PCI bus addresses are translated to system memory addresses for 201 the accesses (such as DMA) initiated by the downstream devices. These 202 windows are derived from the ``dma-ranges`` property. 203 204The PCI core parses ``ranges`` and ``dma-ranges`` into the Host Bridge 205resource lists, and the driver programs one translation window per entry. 206Note that the CPU address and the PCI bus address of a window may differ, 207so the offset between them has to be accounted for while programming the 208windows. 209 210NOTE: If the hardware supports ECAM, it is strongly recommended to use ECAM 211for the Configuration Space so a translation window need not be 212reprogrammed for every Configuration access. 213 214Interrupt Handling 215~~~~~~~~~~~~~~~~~~ 216 217Downstream devices can signal interrupts either through INTx or through 218Message Signaled Interrupts (MSI/MSI-X). The driver has to enable the 219mechanisms supported by the Root Complex. 220 221INTx interrupts are conveyed to the Root Complex through the Assert_INTx 222and Deassert_INTx messages and are then reported as system interrupts. The 223driver typically creates an IRQ domain for the four interrupts (INTA to 224INTD) and demultiplexes an incoming interrupt to the corresponding virtual 225IRQ. 226 227An MSI/MSI-X is signaled by the downstream device as a Memory Write to a 228Root Complex-specific address. There are two ways to handle them: 229 230- If the Root Complex integrates its own MSI controller, the driver has to 231 create an MSI IRQ domain, program the MSI target address and demultiplex 232 the incoming MSIs to the corresponding virtual IRQs. MSI-X is handled 233 through the same domain. 234 235- If the MSIs are handled by an external interrupt controller (such as the 236 GIC ITS), the Root Complex Devicetree node needs to have an 237 ``msi-parent`` property and the driver need not implement an MSI 238 controller. 239 240 241Powering up the Slot/Endpoint 242~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 243 244Power ON any slots or Endpoints connected to the bus with the help of the 245PWRCTRL subsystem APIs such as pci_pwrctrl_create_devices() and 246pci_pwrctrl_power_on_devices(). Note that this requires defining the 247supplies in the Root Port or Endpoint Devicetree node. 248 249Link Training 250~~~~~~~~~~~~~ 251 252Once the resources are initialized, the driver has to initiate Link 253training by enabling the LTSSM (Link Training and Status State Machine) of 254the Root Port. If a PERST# signal is present, it should be deasserted to 255bring the downstream device out of fundamental reset before enabling the 256LTSSM. 257 258Before PERST# is deasserted, the driver must satisfy the power sequencing 259delays defined by the PCI Express Card Electromechanical (CEM) 260Specification. The power supplies must be stable for at least T_PVPERL 261(``PCIE_T_PVPERL_MS``, 100 ms) and the reference clock must be stable for 262at least T_PERST-CLK (``PCIE_T_PERST_CLK_US``, 100 us) before PERST# is 263deasserted. 264 265After the LTSSM is enabled, the driver should wait (with a timeout) for the 266LTSSM to reach the L0 state, indicating that the Link is up. 267 268Once the Link is up, the PCI Express Base Specification (Conventional 269Reset) requires software to wait for at least ``PCIE_RESET_CONFIG_WAIT_MS`` 270(100 ms) before sending the first Configuration Request to the downstream 271device. For a Link operating up to 5.0 GT/s, this delay is counted from the 272exit of the Conventional Reset (PERST# deassertion), while for a Link 273operating above 5.0 GT/s it is counted from the completion of Link 274training. The driver should honor this delay before the bus is scanned. 275 276NOTE: A failure to establish the Link should NOT be treated as a probe 277failure unless the Root Port is not Hotplug capable. If the Root Port is 278Hotplug capable, then the driver should still register the Host Bridge and 279scan the bus, so that the downstream device can be discovered later when 280the Link comes up. 281 282Register the Host Bridge 283~~~~~~~~~~~~~~~~~~~~~~~~ 284 285Finally, allocate the Host Bridge device with devm_pci_alloc_host_bridge(), 286assign the Configuration Space accessors (struct pci_ops) to it, and start 287the bus scan by calling pci_host_probe(). This is the last step of the 288probe(). pci_host_probe() creates the Root bus for the Host Bridge and 289scans/enumerates all the Root Port, RCiEP and Endpoint devices connected to 290the bus. 291 292If the Root Complex IP is from a known IP vendor, the IP specific helpers 293should be reused for the above operations wherever applicable. 294 295Power Management 296---------------- 297 298A Host Controller driver participates in both runtime and system-wide power 299management. In both cases, the driver is responsible for the power state of 300the Root Complex hardware, while the PCI core manages the power state of 301the enumerated devices. 302 303Runtime PM 304~~~~~~~~~~ 305 306Runtime PM allows the Root Complex hardware to be powered down when it is 307idle. The driver typically enables runtime PM with pm_runtime_enable() and 308takes a reference with pm_runtime_get_sync() during probe(), so that the 309controller stays powered while it is in use. The reference is dropped in 310remove(). 311 312If the Root Complex can be powered down when idle, the driver implements 313the runtime_suspend and runtime_resume callbacks to disable and enable the 314controller resources such as the clocks, PHYs, and power domain. These 315callbacks should manage only the controller resources and must not touch 316the state of the enumerated devices, which is handled by the PCI core. 317 318System PM 319~~~~~~~~~ 320 321During system suspend and resume, the driver has to save and restore the 322state of the Root Complex and put the Link into a low power state. 323 324These operations are performed in the _noirq() PM callbacks (for example, 325using NOIRQ_SYSTEM_SLEEP_PM_OPS()), because the controller resources such 326as the clocks and PHY are shared by all the child devices. Suspending them 327earlier would break the child devices whose own suspend callbacks may still 328access their Configuration Space. 329 330In the suspend callback, the driver should: 331 332- Broadcast a PME_Turn_Off message and wait for the PME_TO_Ack, so that the 333 Link can transition to the L2/L3 state. 334- Stop the LTSSM and disable the controller resources such as the clocks, 335 PHY and power domain. 336- Save any controller state that is not retained across the low power 337 state. 338- Power off the downstream devices using pci_pwrctrl_power_off_devices(). 339 340In the resume callback, the driver should reverse the above by enabling the 341controller resources, restoring the saved state, re-initializing the Root 342Complex and re-establishing the Link as done during probe(). 343 344NOTE: If the Link is in the ASPM L1 (or L1 substates) state, some drivers 345keep the Link in L1 across suspend for a faster resume, instead of 346transitioning it to L2/L3. This is a driver policy decision based on the 347platform and the devices connected. 348 349Shutdown 350-------- 351 352The shutdown() callback is invoked during system reboot or when 353transitioning to a new kernel through kexec. Its purpose is to quiesce the 354Root Complex so that the downstream devices cannot corrupt the memory or 355interrupt the new kernel. 356 357The driver should: 358 359- Disable the interrupts (INTx and MSI) reported by the Root Complex so 360 that no spurious interrupt is delivered to the new kernel. 361- Broadcast a PME_Turn_Off message and stop the LTSSM to bring the Link 362 down so that any in-flight DMA from the downstream devices is stopped 363 before the reset. 364- Power down the controller resources. 365 366Unlike remove(), shutdown() does not need to tear down the software state 367such as the Root bus, since the system is going down anyway. 368 369NOTE: shutdown() is optional. It is mainly required on platforms where the 370downstream devices could perform DMA or raise interrupts during the 371transition to reboot or kexec. 372 373Remove 374------ 375 376remove() is called when the driver is detached, and it should undo 377everything done in probe() in the reverse order. 378 379The first step is to remove the enumerated devices and the Root bus, by 380calling pci_stop_root_bus() followed by pci_remove_root_bus() under the 381pci_lock_rescan_remove() lock. This detaches all the child devices before 382the controller resources are released. 383 384After the bus is removed, the driver should: 385 386- Disable the interrupts reported by the Root Complex. 387- Stop the LTSSM to bring the Link down. 388- Power down the PHY and disable the clocks, regulators and resets. 389- Drop the runtime PM reference with pm_runtime_put_sync() and disable 390 runtime PM with pm_runtime_disable(). 391 392Resources allocated through the devm_*() APIs are released automatically 393after remove() returns and need not be freed explicitly. 394 395NOTE: A Host Controller driver is encouraged to be built as a loadable 396module, but it should not be removed at runtime if it implements its own 397IRQ domains such as MSI or INTx controllers. The IRQ mappings created for 398such domains can persist even after the interrupts are released and cannot 399be disposed of safely, so tearing down the IRQ domains on removal is 400fragile. Such drivers should therefore prevent their removal. See the 401following thread for more details: 402https://lore.kernel.org/linux-pci/87k085xekg.wl-maz@kernel.org/ 403