About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / PCI / PCIEBUS-HOWTO.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog