1 .. SPDX-License-Identifier: GPL-2.0
2 .. include:: <isonum.txt>
3
4 ===========================================
5 The PCI Express Port Bus Driver Guide HOWTO
6 ===========================================
7
8 :Author: Tom L Nguyen tom.l.nguyen@intel.com 1
9 :Copyright: |copy| 2004 Intel Corporation
10
11 About this guide
12 ================
13
14 This guide describes the basics of the PCI Exp
15 and provides information on how to enable the
16 register/unregister with the PCI Express Port
17
18
19 What is the PCI Express Port Bus Driver
20 =======================================
21
22 A PCI Express Port is a logical PCI-PCI Bridge
23 are two types of PCI Express Port: the Root Po
24 Port. The Root Port originates a PCI Express l
25 Root Complex and the Switch Port connects PCI
26 internal logical PCI buses. The Switch Port, w
27 bus representing the switch's internal routing
28 switch's Upstream Port. The switch's Downstrea
29 switch's internal routing bus to a bus represe
30 PCI Express link from the PCI Express Switch.
31
32 A PCI Express Port can provide up to four dist
33 referred to in this document as services, depe
34 PCI Express Port's services include native hot
35 power management event support (PME), advanced
36 support (AER), and virtual channel support (VC
37 be handled by a single complex driver or be in
38 and handled by corresponding service drivers.
39
40 Why use the PCI Express Port Bus Driver?
41 ========================================
42
43 In existing Linux kernels, the Linux Device Dr
44 physical device to be handled by only a single
45 Express Port is a PCI-PCI Bridge device with m
46 services. To maintain a clean and simple solut
47 may have its own software service driver. In t
48 service drivers will compete for a single PCI-
49 For example, if the PCI Express Root Port nati
50 driver is loaded first, it claims a PCI-PCI Br
51 kernel therefore does not load other service d
52 Port. In other words, it is impossible to have
53 drivers load and run on a PCI-PCI Bridge devic
54 using the current driver model.
55
56 To enable multiple service drivers running sim
57 having a PCI Express Port Bus driver, which ma
58 PCI Express Ports and distributes all provided
59 to the corresponding service drivers as requir
60 advantages of using the PCI Express Port Bus d
61
62 - Allow multiple service drivers to run simu
63 a PCI-PCI Bridge Port device.
64
65 - Allow service drivers implemented in an in
66 staged approach.
67
68 - Allow one service driver to run on multipl
69 Port devices.
70
71 - Manage and distribute resources of a PCI-P
72 device to requested service drivers.
73
74 Configuring the PCI Express Port Bus Driver vs
75 ==============================================
76
77 Including the PCI Express Port Bus Driver Supp
78 ----------------------------------------------
79
80 Including the PCI Express Port Bus driver depe
81 Express support is included in the kernel conf
82 automatically include the PCI Express Port Bus
83 driver when the PCI Express support is enabled
84
85 Enabling Service Driver Support
86 -------------------------------
87
88 PCI device drivers are implemented based on Li
89 All service drivers are PCI device drivers. As
90 impossible to load any service driver once the
91 PCI Express Port Bus Driver. To meet the PCI E
92 Model requires some minimal changes on existin
93 imposes no impact on the functionality of exis
94
95 A service driver is required to use the two AP
96 register its service with the PCI Express Port
97 section 5.2.1 & 5.2.2). It is important that a
98 initializes the pcie_port_service_driver data
99 header file /include/linux/pcieport_if.h, befo
100 Failure to do so will result an identity misma
101 the PCI Express Port Bus driver from loading a
102
103 pcie_port_service_register
104 ~~~~~~~~~~~~~~~~~~~~~~~~~~
105 ::
106
107 int pcie_port_service_register(struct pcie_p
108
109 This API replaces the Linux Driver Model's pci
110 service driver should always calls pcie_port_s
111 module init. Note that after service driver be
112 such as pci_enable_device(dev) and pci_set_mas
113 necessary since these calls are executed by th
114
115 pcie_port_service_unregister
116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117 ::
118
119 void pcie_port_service_unregister(struct pci
120
121 pcie_port_service_unregister replaces the Linu
122 pci_unregister_driver. It's always called by s
123 module exits.
124
125 Sample Code
126 ~~~~~~~~~~~
127
128 Below is sample service driver code to initial
129 driver data structure.
130 ::
131
132 static struct pcie_port_service_id service_i
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_
141 .name = (char *)device_name,
142 .id_table = service_id,
143
144 .probe = aerdrv_load,
145 .remove = aerdrv_unload,
146
147 .suspend = aerdrv_suspend,
148 .resume = aerdrv_resume,
149 };
150
151 Below is a sample code for registering/unregis
152 driver.
153 ::
154
155 static int __init aerdrv_service_init(void)
156 {
157 int retval = 0;
158
159 retval = pcie_port_service_register(&root_
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
176 Possible Resource Conflicts
177 ===========================
178
179 Since all service drivers of a PCI-PCI Bridge
180 allowed to run simultaneously, below lists a f
181 conflicts with proposed solutions.
182
183 MSI and MSI-X Vector Resource
184 -----------------------------
185
186 Once MSI or MSI-X interrupts are enabled on a
187 mode until they are disabled again. Since ser
188 PCI-PCI Bridge port share the same physical de
189 service driver enables or disables MSI/MSI-X m
190 unpredictable behavior.
191
192 To avoid this situation all service drivers ar
193 switch interrupt mode on its device. The PCI E
194 is responsible for determining the interrupt m
195 transparent to service drivers. Service driver
196 the vector IRQ assigned to the field irq of st
197 is passed in when the PCI Express Port Bus dri
198 driver. Service drivers should use (struct pci
199 call request_irq/free_irq. In addition, the in
200 in the field interrupt_mode of struct pcie_dev
201
202 PCI Memory/IO Mapped Regions
203 ----------------------------
204
205 Service drivers for PCI Express Power Manageme
206 Error Reporting (AER), Hot-Plug (HP) and Virtu
207 PCI configuration space on the PCI Express por
208 registers accessed are independent of each oth
209 that all service drivers will be well behaved
210 other service driver's configuration settings.
211
212 PCI Config Registers
213 --------------------
214
215 Each service driver runs its PCI config operat
216 capability structure except the PCI Express ca
217 that is shared between many drivers including
218 RMW Capability accessors (pcie_capability_clea
219 pcie_capability_set_word(), and pcie_capabilit
220 a selected set of PCI Express Capability Regis
221 Register and Root Control Register). Any chang
222 should be performed using RMW accessors to avo
223 concurrent updates. For the up-to-date list of
224 see pcie_capability_clear_and_set_word().
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.