0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 ===========================================
0005 The PCI Express Port Bus Driver Guide HOWTO
0006 ===========================================
0007
0008 :Author: Tom L Nguyen tom.l.nguyen@intel.com 11/03/2004
0009 :Copyright: |copy| 2004 Intel Corporation
0010
0011 About this guide
0012 ================
0013
0014 This guide describes the basics of the PCI Express Port Bus driver
0015 and provides information on how to enable the service drivers to
0016 register/unregister with the PCI Express Port Bus Driver.
0017
0018
0019 What is the PCI Express Port Bus Driver
0020 =======================================
0021
0022 A PCI Express Port is a logical PCI-PCI Bridge structure. There
0023 are two types of PCI Express Port: the Root Port and the Switch
0024 Port. The Root Port originates a PCI Express link from a PCI Express
0025 Root Complex and the Switch Port connects PCI Express links to
0026 internal logical PCI buses. The Switch Port, which has its secondary
0027 bus representing the switch's internal routing logic, is called the
0028 switch's Upstream Port. The switch's Downstream Port is bridging from
0029 switch's internal routing bus to a bus representing the downstream
0030 PCI Express link from the PCI Express Switch.
0031
0032 A PCI Express Port can provide up to four distinct functions,
0033 referred to in this document as services, depending on its port type.
0034 PCI Express Port's services include native hotplug support (HP),
0035 power management event support (PME), advanced error reporting
0036 support (AER), and virtual channel support (VC). These services may
0037 be handled by a single complex driver or be individually distributed
0038 and handled by corresponding service drivers.
0039
0040 Why use the PCI Express Port Bus Driver?
0041 ========================================
0042
0043 In existing Linux kernels, the Linux Device Driver Model allows a
0044 physical device to be handled by only a single driver. The PCI
0045 Express Port is a PCI-PCI Bridge device with multiple distinct
0046 services. To maintain a clean and simple solution each service
0047 may have its own software service driver. In this case several
0048 service drivers will compete for a single PCI-PCI Bridge device.
0049 For example, if the PCI Express Root Port native hotplug service
0050 driver is loaded first, it claims a PCI-PCI Bridge Root Port. The
0051 kernel therefore does not load other service drivers for that Root
0052 Port. In other words, it is impossible to have multiple service
0053 drivers load and run on a PCI-PCI Bridge device simultaneously
0054 using the current driver model.
0055
0056 To enable multiple service drivers running simultaneously requires
0057 having a PCI Express Port Bus driver, which manages all populated
0058 PCI Express Ports and distributes all provided service requests
0059 to the corresponding service drivers as required. Some key
0060 advantages of using the PCI Express Port Bus driver are listed below:
0061
0062 - Allow multiple service drivers to run simultaneously on
0063 a PCI-PCI Bridge Port device.
0064
0065 - Allow service drivers implemented in an independent
0066 staged approach.
0067
0068 - Allow one service driver to run on multiple PCI-PCI Bridge
0069 Port devices.
0070
0071 - Manage and distribute resources of a PCI-PCI Bridge Port
0072 device to requested service drivers.
0073
0074 Configuring the PCI Express Port Bus Driver vs. Service Drivers
0075 ===============================================================
0076
0077 Including the PCI Express Port Bus Driver Support into the Kernel
0078 -----------------------------------------------------------------
0079
0080 Including the PCI Express Port Bus driver depends on whether the PCI
0081 Express support is included in the kernel config. The kernel will
0082 automatically include the PCI Express Port Bus driver as a kernel
0083 driver when the PCI Express support is enabled in the kernel.
0084
0085 Enabling Service Driver Support
0086 -------------------------------
0087
0088 PCI device drivers are implemented based on Linux Device Driver Model.
0089 All service drivers are PCI device drivers. As discussed above, it is
0090 impossible to load any service driver once the kernel has loaded the
0091 PCI Express Port Bus Driver. To meet the PCI Express Port Bus Driver
0092 Model requires some minimal changes on existing service drivers that
0093 imposes no impact on the functionality of existing service drivers.
0094
0095 A service driver is required to use the two APIs shown below to
0096 register its service with the PCI Express Port Bus driver (see
0097 section 5.2.1 & 5.2.2). It is important that a service driver
0098 initializes the pcie_port_service_driver data structure, included in
0099 header file /include/linux/pcieport_if.h, before calling these APIs.
0100 Failure to do so will result an identity mismatch, which prevents
0101 the PCI Express Port Bus driver from loading a service driver.
0102
0103 pcie_port_service_register
0104 ~~~~~~~~~~~~~~~~~~~~~~~~~~
0105 ::
0106
0107 int pcie_port_service_register(struct pcie_port_service_driver *new)
0108
0109 This API replaces the Linux Driver Model's pci_register_driver API. A
0110 service driver should always calls pcie_port_service_register at
0111 module init. Note that after service driver being loaded, calls
0112 such as pci_enable_device(dev) and pci_set_master(dev) are no longer
0113 necessary since these calls are executed by the PCI Port Bus driver.
0114
0115 pcie_port_service_unregister
0116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0117 ::
0118
0119 void pcie_port_service_unregister(struct pcie_port_service_driver *new)
0120
0121 pcie_port_service_unregister replaces the Linux Driver Model's
0122 pci_unregister_driver. It's always called by service driver when a
0123 module exits.
0124
0125 Sample Code
0126 ~~~~~~~~~~~
0127
0128 Below is sample service driver code to initialize the port service
0129 driver data structure.
0130 ::
0131
0132 static struct pcie_port_service_id service_id[] = { {
0133 .vendor = PCI_ANY_ID,
0134 .device = PCI_ANY_ID,
0135 .port_type = PCIE_RC_PORT,
0136 .service_type = PCIE_PORT_SERVICE_AER,
0137 }, { /* end: all zeroes */ }
0138 };
0139
0140 static struct pcie_port_service_driver root_aerdrv = {
0141 .name = (char *)device_name,
0142 .id_table = &service_id[0],
0143
0144 .probe = aerdrv_load,
0145 .remove = aerdrv_unload,
0146
0147 .suspend = aerdrv_suspend,
0148 .resume = aerdrv_resume,
0149 };
0150
0151 Below is a sample code for registering/unregistering a service
0152 driver.
0153 ::
0154
0155 static int __init aerdrv_service_init(void)
0156 {
0157 int retval = 0;
0158
0159 retval = pcie_port_service_register(&root_aerdrv);
0160 if (!retval) {
0161 /*
0162 * FIX ME
0163 */
0164 }
0165 return retval;
0166 }
0167
0168 static void __exit aerdrv_service_exit(void)
0169 {
0170 pcie_port_service_unregister(&root_aerdrv);
0171 }
0172
0173 module_init(aerdrv_service_init);
0174 module_exit(aerdrv_service_exit);
0175
0176 Possible Resource Conflicts
0177 ===========================
0178
0179 Since all service drivers of a PCI-PCI Bridge Port device are
0180 allowed to run simultaneously, below lists a few of possible resource
0181 conflicts with proposed solutions.
0182
0183 MSI and MSI-X Vector Resource
0184 -----------------------------
0185
0186 Once MSI or MSI-X interrupts are enabled on a device, it stays in this
0187 mode until they are disabled again. Since service drivers of the same
0188 PCI-PCI Bridge port share the same physical device, if an individual
0189 service driver enables or disables MSI/MSI-X mode it may result
0190 unpredictable behavior.
0191
0192 To avoid this situation all service drivers are not permitted to
0193 switch interrupt mode on its device. The PCI Express Port Bus driver
0194 is responsible for determining the interrupt mode and this should be
0195 transparent to service drivers. Service drivers need to know only
0196 the vector IRQ assigned to the field irq of struct pcie_device, which
0197 is passed in when the PCI Express Port Bus driver probes each service
0198 driver. Service drivers should use (struct pcie_device*)dev->irq to
0199 call request_irq/free_irq. In addition, the interrupt mode is stored
0200 in the field interrupt_mode of struct pcie_device.
0201
0202 PCI Memory/IO Mapped Regions
0203 ----------------------------
0204
0205 Service drivers for PCI Express Power Management (PME), Advanced
0206 Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access
0207 PCI configuration space on the PCI Express port. In all cases the
0208 registers accessed are independent of each other. This patch assumes
0209 that all service drivers will be well behaved and not overwrite
0210 other service driver's configuration settings.
0211
0212 PCI Config Registers
0213 --------------------
0214
0215 Each service driver runs its PCI config operations on its own
0216 capability structure except the PCI Express capability structure, in
0217 which Root Control register and Device Control register are shared
0218 between PME and AER. This patch assumes that all service drivers
0219 will be well behaved and not overwrite other service driver's
0220 configuration settings.
