1.. SPDX-License-Identifier: GPL-2.0
2.. include:: <isonum.txt>
3
4===========================================
5The PCI Express Port Bus Driver Guide HOWTO
6===========================================
7
8:Author: Tom L Nguyen tom.l.nguyen@intel.com 11/03/2004
9:Copyright: |copy| 2004 Intel Corporation
10
11About this guide
12================
13
14This guide describes the basics of the PCI Express Port Bus driver
15and provides information on how to enable the service drivers to
16register/unregister with the PCI Express Port Bus Driver.
17
18
19What is the PCI Express Port Bus Driver
20=======================================
21
22A PCI Express Port is a logical PCI-PCI Bridge structure. There
23are two types of PCI Express Port: the Root Port and the Switch
24Port. The Root Port originates a PCI Express link from a PCI Express
25Root Complex and the Switch Port connects PCI Express links to
26internal logical PCI buses. The Switch Port, which has its secondary
27bus representing the switch's internal routing logic, is called the
28switch's Upstream Port. The switch's Downstream Port is bridging from
29switch's internal routing bus to a bus representing the downstream
30PCI Express link from the PCI Express Switch.
31
32A PCI Express Port can provide up to four distinct functions,
33referred to in this document as services, depending on its port type.
34PCI Express Port's services include native hotplug support (HP),
35power management event support (PME), advanced error reporting
36support (AER), and virtual channel support (VC). These services may
37be handled by a single complex driver or be individually distributed
38and handled by corresponding service drivers.
39
40Why use the PCI Express Port Bus Driver?
41========================================
42
43In existing Linux kernels, the Linux Device Driver Model allows a
44physical device to be handled by only a single driver. The PCI
45Express Port is a PCI-PCI Bridge device with multiple distinct
46services. To maintain a clean and simple solution each service
47may have its own software service driver. In this case several
48service drivers will compete for a single PCI-PCI Bridge device.
49For example, if the PCI Express Root Port native hotplug service
50driver is loaded first, it claims a PCI-PCI Bridge Root Port. The
51kernel therefore does not load other service drivers for that Root
52Port. In other words, it is impossible to have multiple service
53drivers load and run on a PCI-PCI Bridge device simultaneously
54using the current driver model.
55
56To enable multiple service drivers running simultaneously requires
57having a PCI Express Port Bus driver, which manages all populated
58PCI Express Ports and distributes all provided service requests
59to the corresponding service drivers as required. Some key
60advantages of using the PCI Express Port Bus driver are listed below:
61
62  - Allow multiple service drivers to run simultaneously on
63    a PCI-PCI Bridge Port device.
64
65  - Allow service drivers implemented in an independent
66    staged approach.
67
68  - Allow one service driver to run on multiple PCI-PCI Bridge
69    Port devices.
70
71  - Manage and distribute resources of a PCI-PCI Bridge Port
72    device to requested service drivers.
73
74Configuring the PCI Express Port Bus Driver vs. Service Drivers
75===============================================================
76
77Including the PCI Express Port Bus Driver Support into the Kernel
78-----------------------------------------------------------------
79
80Including the PCI Express Port Bus driver depends on whether the PCI
81Express support is included in the kernel config. The kernel will
82automatically include the PCI Express Port Bus driver as a kernel
83driver when the PCI Express support is enabled in the kernel.
84
85Enabling Service Driver Support
86-------------------------------
87
88PCI device drivers are implemented based on Linux Device Driver Model.
89All service drivers are PCI device drivers. As discussed above, it is
90impossible to load any service driver once the kernel has loaded the
91PCI Express Port Bus Driver. To meet the PCI Express Port Bus Driver
92Model requires some minimal changes on existing service drivers that
93imposes no impact on the functionality of existing service drivers.
94
95A service driver is required to use the two APIs shown below to
96register its service with the PCI Express Port Bus driver (see
97section 5.2.1 & 5.2.2). It is important that a service driver
98initializes the pcie_port_service_driver data structure, included in
99header file /include/linux/pcieport_if.h, before calling these APIs.
100Failure to do so will result an identity mismatch, which prevents
101the PCI Express Port Bus driver from loading a service driver.
102
103pcie_port_service_register
104~~~~~~~~~~~~~~~~~~~~~~~~~~
105::
106
107  int pcie_port_service_register(struct pcie_port_service_driver *new)
108
109This API replaces the Linux Driver Model's pci_register_driver API. A
110service driver should always calls pcie_port_service_register at
111module init. Note that after service driver being loaded, calls
112such as pci_enable_device(dev) and pci_set_master(dev) are no longer
113necessary since these calls are executed by the PCI Port Bus driver.
114
115pcie_port_service_unregister
116~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117::
118
119  void pcie_port_service_unregister(struct pcie_port_service_driver *new)
120
121pcie_port_service_unregister replaces the Linux Driver Model's
122pci_unregister_driver. It's always called by service driver when a
123module exits.
124
125Sample Code
126~~~~~~~~~~~
127
128Below is sample service driver code to initialize the port service
129driver data structure.
130::
131
132  static struct pcie_port_service_id service_id[] = { {
133    .vendor = PCI_ANY_ID,
134    .device = PCI_ANY_ID,
135    .port_type = PCIE_RC_PORT,
136    .service_type = PCIE_PORT_SERVICE_AER,
137    }, { /* end: all zeroes */ }
138  };
139
140  static struct pcie_port_service_driver root_aerdrv = {
141    .name		= (char *)device_name,
142    .id_table	= &service_id[0],
143
144    .probe		= aerdrv_load,
145    .remove		= aerdrv_unload,
146
147    .suspend	= aerdrv_suspend,
148    .resume		= aerdrv_resume,
149  };
150
151Below is a sample code for registering/unregistering a service
152driver.
153::
154
155  static int __init aerdrv_service_init(void)
156  {
157    int retval = 0;
158
159    retval = pcie_port_service_register(&root_aerdrv);
160    if (!retval) {
161      /*
162      * FIX ME
163      */
164    }
165    return retval;
166  }
167
168  static void __exit aerdrv_service_exit(void)
169  {
170    pcie_port_service_unregister(&root_aerdrv);
171  }
172
173  module_init(aerdrv_service_init);
174  module_exit(aerdrv_service_exit);
175
176Possible Resource Conflicts
177===========================
178
179Since all service drivers of a PCI-PCI Bridge Port device are
180allowed to run simultaneously, below lists a few of possible resource
181conflicts with proposed solutions.
182
183MSI and MSI-X Vector Resource
184-----------------------------
185
186Once MSI or MSI-X interrupts are enabled on a device, it stays in this
187mode until they are disabled again.  Since service drivers of the same
188PCI-PCI Bridge port share the same physical device, if an individual
189service driver enables or disables MSI/MSI-X mode it may result
190unpredictable behavior.
191
192To avoid this situation all service drivers are not permitted to
193switch interrupt mode on its device. The PCI Express Port Bus driver
194is responsible for determining the interrupt mode and this should be
195transparent to service drivers. Service drivers need to know only
196the vector IRQ assigned to the field irq of struct pcie_device, which
197is passed in when the PCI Express Port Bus driver probes each service
198driver. Service drivers should use (struct pcie_device*)dev->irq to
199call request_irq/free_irq. In addition, the interrupt mode is stored
200in the field interrupt_mode of struct pcie_device.
201
202PCI Memory/IO Mapped Regions
203----------------------------
204
205Service drivers for PCI Express Power Management (PME), Advanced
206Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access
207PCI configuration space on the PCI Express port. In all cases the
208registers accessed are independent of each other. This patch assumes
209that all service drivers will be well behaved and not overwrite
210other service driver's configuration settings.
211
212PCI Config Registers
213--------------------
214
215Each service driver runs its PCI config operations on its own
216capability structure except the PCI Express capability structure,
217that is shared between many drivers including the service drivers.
218RMW Capability accessors (pcie_capability_clear_and_set_word(),
219pcie_capability_set_word(), and pcie_capability_clear_word()) protect
220a selected set of PCI Express Capability Registers (Link Control
221Register and Root Control Register). Any change to those registers
222should be performed using RMW accessors to avoid problems due to
223concurrent updates. For the up-to-date list of protected registers,
224see pcie_capability_clear_and_set_word().
225