Documentation: PCI: convert pci.txt to reST

Convert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change. Move the description of struct pci_driver and struct pci_device_id into in-source comments.

Changbin Du committed 7 years ago

Commit 229b4e01 parent c42eaff4 files · +222 −213Browse files

Unified · Split

4 files

Documentation/PCI/index.rst +2 −0
Documentation/PCI/pci.rst +149 −207
include/linux/mod_devicetable.h +24 −5
include/linux/pci.h +47 −1

Documentation/PCI/index.rst+2−0

@@ -7,3 +7,5 @@ Linux PCI Bus Subsystem · 6 unmodified lines
7	.. toctree::	7	.. toctree::
8	:maxdepth: 2	8	:maxdepth: 2
9	:numbered:	9	:numbered:
		10
		11	pci

Documentation/PCI/pci.rstrenamed from Documentation/PCI/pci.txt+149−207

@@ -1,10 +1,12 @@
		1	.. SPDX-License-Identifier: GPL-2.0
1		2
2	How To Write Linux PCI Drivers	3	==============================
		4	How To Write Linux PCI Drivers
		5	==============================
3		6
4	by Martin Mares <mj@ucw.cz> on 07-Feb-2000	7	:Authors: - Martin Mares <mj@ucw.cz>
5	updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006	8	- Grant Grundler <grundler@parisc-linux.org>
6		9
7	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8	The world of PCI is vast and full of (mostly unpleasant) surprises.	10	The world of PCI is vast and full of (mostly unpleasant) surprises.
9	Since each CPU architecture implements different chip-sets and PCI devices	11	Since each CPU architecture implements different chip-sets and PCI devices
10	have different requirements (erm, "features"), the result is the PCI support	12	have different requirements (erm, "features"), the result is the PCI support
@@ -15,8 +17,7 @@ PCI device drivers. · 4 unmodified lines
15	A more complete resource is the third edition of "Linux Device Drivers"	17	A more complete resource is the third edition of "Linux Device Drivers"
16	by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.	18	by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
17	LDD3 is available for free (under Creative Commons License) from:	19	LDD3 is available for free (under Creative Commons License) from:
18		20	http://lwn.net/Kernel/LDD3/.
19	http://lwn.net/Kernel/LDD3/
20		21
21	However, keep in mind that all documents are subject to "bit rot".	22	However, keep in mind that all documents are subject to "bit rot".
22	Refer to the source code if things are not working as described here.	23	Refer to the source code if things are not working as described here.
@@ -25,9 +26,8 @@ Please send questions/comments/patches about Linux PCI API to the · 2 unmodified lines
25	"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.	26	"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
26		27
27		28
28		29	Structure of PCI drivers
29	0. Structure of PCI drivers	30	========================
30	~~~~~~~~~~~~~~~~~~~~~~~~~~~
31	PCI drivers "discover" PCI devices in a system via pci_register_driver().	31	PCI drivers "discover" PCI devices in a system via pci_register_driver().
32	Actually, it's the other way around. When the PCI generic code discovers	32	Actually, it's the other way around. When the PCI generic code discovers
33	a new device, the driver with a matching "description" will be notified.	33	a new device, the driver with a matching "description" will be notified.
@@ -42,24 +42,25 @@ pointers and thus dictates the high level structure of a driver. · 8 unmodified lines
42	Once the driver knows about a PCI device and takes ownership, the	42	Once the driver knows about a PCI device and takes ownership, the
43	driver generally needs to perform the following initialization:	43	driver generally needs to perform the following initialization:
44		44
45	Enable the device	45	- Enable the device
46	Request MMIO/IOP resources	46	- Request MMIO/IOP resources
47	Set the DMA mask size (for both coherent and streaming DMA)	47	- Set the DMA mask size (for both coherent and streaming DMA)
48	Allocate and initialize shared control data (pci_allocate_coherent())	48	- Allocate and initialize shared control data (pci_allocate_coherent())
49	Access device configuration space (if needed)	49	- Access device configuration space (if needed)
50	Register IRQ handler (request_irq())	50	- Register IRQ handler (request_irq())
51	Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)	51	- Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
52	Enable DMA/processing engines	52	- Enable DMA/processing engines
53		53
54	When done using the device, and perhaps the module needs to be unloaded,	54	When done using the device, and perhaps the module needs to be unloaded,
55	the driver needs to take the follow steps:	55	the driver needs to take the follow steps:
56	Disable the device from generating IRQs	56
57	Release the IRQ (free_irq())	57	- Disable the device from generating IRQs
58	Stop all DMA activity	58	- Release the IRQ (free_irq())
59	Release DMA buffers (both streaming and coherent)	59	- Stop all DMA activity
60	Unregister from other subsystems (e.g. scsi or netdev)	60	- Release DMA buffers (both streaming and coherent)
61	Release MMIO/IOP resources	61	- Unregister from other subsystems (e.g. scsi or netdev)
62	Disable the device	62	- Release MMIO/IOP resources
		63	- Disable the device
63		64
64	Most of these topics are covered in the following sections.	65	Most of these topics are covered in the following sections.
65	For the rest look at LDD3 or <linux/pci.h> .	66	For the rest look at LDD3 or <linux/pci.h> .
@@ -70,99 +71,38 @@ completely empty or just returning an appropriate error codes to avoid · 4 unmodified lines
70	lots of ifdefs in the drivers.	71	lots of ifdefs in the drivers.
71		72
72		73
		74	pci_register_driver() call
		75	==========================
73		76
74	1. pci_register_driver() call	77	PCI device drivers call ``pci_register_driver()`` during their
75	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76
77	PCI device drivers call pci_register_driver() during their
78	initialization with a pointer to a structure describing the driver	78	initialization with a pointer to a structure describing the driver
79	(struct pci_driver):	79	(``struct pci_driver``):
80
81	field name Description
82	---------- ------------------------------------------------------
83	id_table Pointer to table of device ID's the driver is
84	interested in. Most drivers should export this
85	table using MODULE_DEVICE_TABLE(pci,...).
86
87	probe This probing function gets called (during execution
88	of pci_register_driver() for already existing
89	devices or later if a new device gets inserted) for
90	all PCI devices which match the ID table and are not
91	"owned" by the other drivers yet. This function gets
92	passed a "struct pci_dev *" for each device whose
93	entry in the ID table matches the device. The probe
94	function returns zero when the driver chooses to
95	take "ownership" of the device or an error code
96	(negative number) otherwise.
97	The probe function always gets called from process
98	context, so it can sleep.
99
100	remove The remove() function gets called whenever a device
101	being handled by this driver is removed (either during
102	deregistration of the driver or when it's manually
103	pulled out of a hot-pluggable slot).
104	The remove function always gets called from process
105	context, so it can sleep.
106
107	suspend Put device into low power state.
108	suspend_late Put device into low power state.
109
110	resume_early Wake device from low power state.
111	resume Wake device from low power state.
112
113	(Please see Documentation/power/pci.txt for descriptions
114	of PCI Power Management and the related functions.)
115
116	shutdown Hook into reboot_notifier_list (kernel/sys.c).
117	Intended to stop any idling DMA operations.
118	Useful for enabling wake-on-lan (NIC) or changing
119	the power state of a device before reboot.
120	e.g. drivers/net/e100.c.
121
122	err_handler See Documentation/PCI/pci-error-recovery.txt
123
124
125	The ID table is an array of struct pci_device_id entries ending with an
126	all-zero entry. Definitions with static const are generally preferred.
127
128	Each entry consists of:
129
130	vendor,device Vendor and device ID to match (or PCI_ANY_ID)
131		80
132	subvendor, Subsystem vendor and device ID to match (or PCI_ANY_ID)	81	.. kernel-doc:: include/linux/pci.h
133	subdevice,	82	:functions: pci_driver
134		83
135	class Device class, subclass, and "interface" to match.	84	The ID table is an array of ``struct pci_device_id`` entries ending with an
136	See Appendix D of the PCI Local Bus Spec or	85	all-zero entry. Definitions with static const are generally preferred.
137	include/linux/pci_ids.h for a full list of classes.
138	Most drivers do not need to specify class/class_mask
139	as vendor/device is normally sufficient.
140
141	class_mask limit which sub-fields of the class field are compared.
142	See drivers/scsi/sym53c8xx_2/ for example of usage.
143
144	driver_data Data private to the driver.
145	Most drivers don't need to use driver_data field.
146	Best practice is to use driver_data as an index
147	into a static list of equivalent device types,
148	instead of using it as a pointer.
149		86
		87	.. kernel-doc:: include/linux/mod_devicetable.h
		88	:functions: pci_device_id
150		89
151	Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up	90	Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up
152	a pci_device_id table.	91	a pci_device_id table.
153		92
154	New PCI IDs may be added to a device driver pci_ids table at runtime	93	New PCI IDs may be added to a device driver pci_ids table at runtime
155	as shown below:	94	as shown below::
156		95
157	echo "vendor device subvendor subdevice class class_mask driver_data" > \	96	echo "vendor device subvendor subdevice class class_mask driver_data" > \
158	/sys/bus/pci/drivers/{driver}/new_id	97	/sys/bus/pci/drivers/{driver}/new_id
159		98
160	All fields are passed in as hexadecimal values (no leading 0x).	99	All fields are passed in as hexadecimal values (no leading 0x).
161	The vendor and device fields are mandatory, the others are optional. Users	100	The vendor and device fields are mandatory, the others are optional. Users
162	need pass only as many optional fields as necessary:	101	need pass only as many optional fields as necessary:
163	o subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)	102
164	o class and classmask fields default to 0	103	- subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
165	o driver_data defaults to 0UL.	104	- class and classmask fields default to 0
		105	- driver_data defaults to 0UL.
166		106
167	Note that driver_data must match the value used by any of the pci_device_id	107	Note that driver_data must match the value used by any of the pci_device_id
168	entries defined in the driver. This makes the driver_data field mandatory	108	entries defined in the driver. This makes the driver_data field mandatory
@@ -175,29 +115,31 @@ When the driver exits, it just calls pci_unregister_driver() and the PCI layer · 6 unmodified lines
175	automatically calls the remove hook for all devices handled by the driver.	115	automatically calls the remove hook for all devices handled by the driver.
176		116
177		117
178	1.1 "Attributes" for driver functions/data	118	"Attributes" for driver functions/data
		119	--------------------------------------
179		120
180	Please mark the initialization and cleanup functions where appropriate	121	Please mark the initialization and cleanup functions where appropriate
181	(the corresponding macros are defined in <linux/init.h>):	122	(the corresponding macros are defined in <linux/init.h>):
182		123
		124	====== =================================================
183	__init Initialization code. Thrown away after the driver	125	__init Initialization code. Thrown away after the driver
184	initializes.	126	initializes.
185	__exit Exit code. Ignored for non-modular drivers.	127	__exit Exit code. Ignored for non-modular drivers.
		128	====== =================================================
186		129
187	Tips on when/where to use the above attributes:	130	Tips on when/where to use the above attributes:
188	o The module_init()/module_exit() functions (and all	131	- The module_init()/module_exit() functions (and all
189	initialization functions called _only_ from these)	132	initialization functions called _only_ from these)
190	should be marked __init/__exit.	133	should be marked __init/__exit.
191		134
192	o Do not mark the struct pci_driver.	135	- Do not mark the struct pci_driver.
193		136
194	o Do NOT mark a function if you are not sure which mark to use.	137	- Do NOT mark a function if you are not sure which mark to use.
195	Better to not mark the function than mark the function wrong.	138	Better to not mark the function than mark the function wrong.
196		139
197		140
198		141	How to find PCI devices manually
199	2. How to find PCI devices manually	142	================================
200	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201		143
202	PCI drivers should have a really good reason for not using the	144	PCI drivers should have a really good reason for not using the
203	pci_register_driver() interface to search for PCI devices.	145	pci_register_driver() interface to search for PCI devices.
@@ -207,17 +149,17 @@ E.g. combined serial/parallel port/floppy controller. · 3 unmodified lines
207		149
208	A manual search may be performed using the following constructs:	150	A manual search may be performed using the following constructs:
209		151
210	Searching by vendor and device ID:	152	Searching by vendor and device ID::
211		153
212	struct pci_dev *dev = NULL;	154	struct pci_dev *dev = NULL;
213	while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))	155	while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
214	configure_device(dev);	156	configure_device(dev);
215		157
216	Searching by class ID (iterate in a similar way):	158	Searching by class ID (iterate in a similar way)::
217		159
218	pci_get_class(CLASS_ID, dev)	160	pci_get_class(CLASS_ID, dev)
219		161
220	Searching by both vendor/device and subsystem vendor/device ID:	162	Searching by both vendor/device and subsystem vendor/device ID::
221		163
222	pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).	164	pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
223		165
@@ -230,21 +172,20 @@ the pci_dev that they return. You must eventually (possibly at module unload) · 6 unmodified lines
230	decrement the reference count on these devices by calling pci_dev_put().	172	decrement the reference count on these devices by calling pci_dev_put().
231		173
232		174
233		175	Device Initialization Steps
234	3. Device Initialization Steps	176	===========================
235	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
236		177
237	As noted in the introduction, most PCI drivers need the following steps	178	As noted in the introduction, most PCI drivers need the following steps
238	for device initialization:	179	for device initialization:
239		180
240	Enable the device	181	- Enable the device
241	Request MMIO/IOP resources	182	- Request MMIO/IOP resources
242	Set the DMA mask size (for both coherent and streaming DMA)	183	- Set the DMA mask size (for both coherent and streaming DMA)
243	Allocate and initialize shared control data (pci_allocate_coherent())	184	- Allocate and initialize shared control data (pci_allocate_coherent())
244	Access device configuration space (if needed)	185	- Access device configuration space (if needed)
245	Register IRQ handler (request_irq())	186	- Register IRQ handler (request_irq())
246	Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)	187	- Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
247	Enable DMA/processing engines.	188	- Enable DMA/processing engines.
248		189
249	The driver can access PCI config space registers at any time.	190	The driver can access PCI config space registers at any time.
250	(Well, almost. When running BIST, config space can go away...but	191	(Well, almost. When running BIST, config space can go away...but
@@ -252,26 +193,29 @@ that will just result in a PCI Bus Master Abort and config reads · 1 unmodified line
252	will return garbage).	193	will return garbage).
253		194
254		195
255	3.1 Enable the PCI device	196	Enable the PCI device
256	~~~~~~~~~~~~~~~~~~~~~~~~~	197	---------------------
257	Before touching any device registers, the driver needs to enable	198	Before touching any device registers, the driver needs to enable
258	the PCI device by calling pci_enable_device(). This will:	199	the PCI device by calling pci_enable_device(). This will:
259	o wake up the device if it was in suspended state,
260	o allocate I/O and memory regions of the device (if BIOS did not),
261	o allocate an IRQ (if BIOS did not).
262		200
263	NOTE: pci_enable_device() can fail! Check the return value.	201	- wake up the device if it was in suspended state,
		202	- allocate I/O and memory regions of the device (if BIOS did not),
		203	- allocate an IRQ (if BIOS did not).
264		204
265	[ OS BUG: we don't check resource allocations before enabling those	205	.. note::
266	resources. The sequence would make more sense if we called	206	pci_enable_device() can fail! Check the return value.
267	pci_request_resources() before calling pci_enable_device().	207
268	Currently, the device drivers can't detect the bug when when two	208	.. warning::
269	devices have been allocated the same range. This is not a common	209	OS BUG: we don't check resource allocations before enabling those
270	problem and unlikely to get fixed soon.	210	resources. The sequence would make more sense if we called
		211	pci_request_resources() before calling pci_enable_device().
		212	Currently, the device drivers can't detect the bug when when two
		213	devices have been allocated the same range. This is not a common
		214	problem and unlikely to get fixed soon.
		215
		216	This has been discussed before but not changed as of 2.6.19:
		217	http://lkml.org/lkml/2006/3/2/194
271		218
272	This has been discussed before but not changed as of 2.6.19:
273	http://lkml.org/lkml/2006/3/2/194
274	]
275		219
276	pci_set_master() will enable DMA by setting the bus master bit	220	pci_set_master() will enable DMA by setting the bus master bit
277	in the PCI_COMMAND register. It also fixes the latency timer value if	221	in the PCI_COMMAND register. It also fixes the latency timer value if
@@ -288,8 +232,8 @@ pci_try_set_mwi() to have the system do its best effort at enabling · 10 unmodified lines
288	Mem-Wr-Inval.	232	Mem-Wr-Inval.
289		233
290		234
291	3.2 Request MMIO/IOP resources	235	Request MMIO/IOP resources
292	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~	236	--------------------------
293	Memory (MMIO), and I/O port addresses should NOT be read directly	237	Memory (MMIO), and I/O port addresses should NOT be read directly
294	from the PCI device config space. Use the values in the pci_dev structure	238	from the PCI device config space. Use the values in the pci_dev structure
295	as the PCI "bus address" might have been remapped to a "host physical"	239	as the PCI "bus address" might have been remapped to a "host physical"
@@ -304,9 +248,10 @@ Conversely, drivers should call pci_release_region() AFTER · 8 unmodified lines
304	calling pci_disable_device().	248	calling pci_disable_device().
305	The idea is to prevent two devices colliding on the same address range.	249	The idea is to prevent two devices colliding on the same address range.
306		250
307	[ See OS BUG comment above. Currently (2.6.19), The driver can only	251	.. tip::
308	determine MMIO and IO Port resource availability _after_ calling	252	See OS BUG comment above. Currently (2.6.19), The driver can only
309	pci_enable_device(). ]	253	determine MMIO and IO Port resource availability _after_ calling
		254	pci_enable_device().
310		255
311	Generic flavors of pci_request_region() are request_mem_region()	256	Generic flavors of pci_request_region() are request_mem_region()
312	(for MMIO ranges) and request_region() (for IO Port ranges).	257	(for MMIO ranges) and request_region() (for IO Port ranges).
@@ -316,12 +261,13 @@ BARs. · 3 unmodified lines
316	Also see pci_request_selected_regions() below.	261	Also see pci_request_selected_regions() below.
317		262
318		263
319	3.3 Set the DMA mask size	264	Set the DMA mask size
320	~~~~~~~~~~~~~~~~~~~~~~~~~	265	---------------------
321	[ If anything below doesn't make sense, please refer to	266	.. note::
322	Documentation/DMA-API.txt. This section is just a reminder that	267	If anything below doesn't make sense, please refer to
323	drivers need to indicate DMA capabilities of the device and is not	268	Documentation/DMA-API.txt. This section is just a reminder that
324	an authoritative source for DMA interfaces. ]	269	drivers need to indicate DMA capabilities of the device and is not
		270	an authoritative source for DMA interfaces.
325		271
326	While all drivers should explicitly indicate the DMA capability	272	While all drivers should explicitly indicate the DMA capability
327	(e.g. 32 or 64 bit) of the PCI bus master, devices with more than	273	(e.g. 32 or 64 bit) of the PCI bus master, devices with more than
@@ -342,23 +288,23 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are · 14 unmodified lines
342	("consistent") data.	288	("consistent") data.
343		289
344		290
345	3.4 Setup shared control data	291	Setup shared control data
346	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~	292	-------------------------
347	Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)	293	Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
348	memory. See Documentation/DMA-API.txt for a full description of	294	memory. See Documentation/DMA-API.txt for a full description of
349	the DMA APIs. This section is just a reminder that it needs to be done	295	the DMA APIs. This section is just a reminder that it needs to be done
350	before enabling DMA on the device.	296	before enabling DMA on the device.
351		297
352		298
353	3.5 Initialize device registers	299	Initialize device registers
354	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~	300	---------------------------
355	Some drivers will need specific "capability" fields programmed	301	Some drivers will need specific "capability" fields programmed
356	or other "vendor specific" register initialized or reset.	302	or other "vendor specific" register initialized or reset.
357	E.g. clearing pending interrupts.	303	E.g. clearing pending interrupts.
358		304
359		305
360	3.6 Register IRQ handler	306	Register IRQ handler
361	~~~~~~~~~~~~~~~~~~~~~~~~	307	--------------------
362	While calling request_irq() is the last step described here,	308	While calling request_irq() is the last step described here,
363	this is often just another intermediate step to initialize a device.	309	this is often just another intermediate step to initialize a device.
364	This step can often be deferred until the device is opened for use.	310	This step can often be deferred until the device is opened for use.
@@ -396,6 +342,7 @@ and msix_enabled flags in the pci_dev structure after calling · 31 unmodified lines
396	pci_alloc_irq_vectors.	342	pci_alloc_irq_vectors.
397		343
398	There are (at least) two really good reasons for using MSI:	344	There are (at least) two really good reasons for using MSI:
		345
399	1) MSI is an exclusive interrupt vector by definition.	346	1) MSI is an exclusive interrupt vector by definition.
400	This means the interrupt handler doesn't have to verify	347	This means the interrupt handler doesn't have to verify
401	its device caused the interrupt.	348	its device caused the interrupt.
@@ -410,24 +357,23 @@ See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples · 8 unmodified lines
410	of MSI/MSI-X usage.	357	of MSI/MSI-X usage.
411		358
412		359
413		360	PCI device shutdown
414	4. PCI device shutdown	361	===================
415	~~~~~~~~~~~~~~~~~~~~~~~
416		362
417	When a PCI device driver is being unloaded, most of the following	363	When a PCI device driver is being unloaded, most of the following
418	steps need to be performed:	364	steps need to be performed:
419		365
420	Disable the device from generating IRQs	366	- Disable the device from generating IRQs
421	Release the IRQ (free_irq())	367	- Release the IRQ (free_irq())
422	Stop all DMA activity	368	- Stop all DMA activity
423	Release DMA buffers (both streaming and consistent)	369	- Release DMA buffers (both streaming and consistent)
424	Unregister from other subsystems (e.g. scsi or netdev)	370	- Unregister from other subsystems (e.g. scsi or netdev)
425	Disable device from responding to MMIO/IO Port addresses	371	- Disable device from responding to MMIO/IO Port addresses
426	Release MMIO/IO Port resource(s)	372	- Release MMIO/IO Port resource(s)
427		373
428		374
429	4.1 Stop IRQs on the device	375	Stop IRQs on the device
430	~~~~~~~~~~~~~~~~~~~~~~~~~~~	376	-----------------------
431	How to do this is chip/device specific. If it's not done, it opens	377	How to do this is chip/device specific. If it's not done, it opens
432	the possibility of a "screaming interrupt" if (and only if)	378	the possibility of a "screaming interrupt" if (and only if)
433	the IRQ is shared with another device.	379	the IRQ is shared with another device.
@@ -446,16 +392,16 @@ MSI and MSI-X are defined to be exclusive interrupts and thus · 12 unmodified lines
446	are not susceptible to the "screaming interrupt" problem.	392	are not susceptible to the "screaming interrupt" problem.
447		393
448		394
449	4.2 Release the IRQ	395	Release the IRQ
450	~~~~~~~~~~~~~~~~~~~	396	---------------
451	Once the device is quiesced (no more IRQs), one can call free_irq().	397	Once the device is quiesced (no more IRQs), one can call free_irq().
452	This function will return control once any pending IRQs are handled,	398	This function will return control once any pending IRQs are handled,
453	"unhook" the drivers IRQ handler from that IRQ, and finally release	399	"unhook" the drivers IRQ handler from that IRQ, and finally release
454	the IRQ if no one else is using it.	400	the IRQ if no one else is using it.
455		401
456		402
457	4.3 Stop all DMA activity	403	Stop all DMA activity
458	~~~~~~~~~~~~~~~~~~~~~~~~~	404	---------------------
459	It's extremely important to stop all DMA operations BEFORE attempting	405	It's extremely important to stop all DMA operations BEFORE attempting
460	to deallocate DMA control data. Failure to do so can result in memory	406	to deallocate DMA control data. Failure to do so can result in memory
461	corruption, hangs, and on some chip-sets a hard crash.	407	corruption, hangs, and on some chip-sets a hard crash.
@@ -467,8 +413,8 @@ While this step sounds obvious and trivial, several "mature" drivers · 5 unmodified lines
467	didn't get this step right in the past.	413	didn't get this step right in the past.
468		414
469		415
470	4.4 Release DMA buffers	416	Release DMA buffers
471	~~~~~~~~~~~~~~~~~~~~~~~	417	-------------------
472	Once DMA is stopped, clean up streaming DMA first.	418	Once DMA is stopped, clean up streaming DMA first.
473	I.e. unmap data buffers and return buffers to "upstream"	419	I.e. unmap data buffers and return buffers to "upstream"
474	owners if there is one.	420	owners if there is one.
@@ -478,8 +424,8 @@ Then clean up "consistent" buffers which contain the control data. · 3 unmodified lines
478	See Documentation/DMA-API.txt for details on unmapping interfaces.	424	See Documentation/DMA-API.txt for details on unmapping interfaces.
479		425
480		426
481	4.5 Unregister from other subsystems	427	Unregister from other subsystems
482	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~	428	--------------------------------
483	Most low level PCI device drivers support some other subsystem	429	Most low level PCI device drivers support some other subsystem
484	like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your	430	like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
485	driver isn't losing resources from that other subsystem.	431	driver isn't losing resources from that other subsystem.
@@ -487,31 +433,30 @@ If this happens, typically the symptom is an Oops (panic) when · 1 unmodified line
487	the subsystem attempts to call into a driver that has been unloaded.	433	the subsystem attempts to call into a driver that has been unloaded.
488		434
489		435
490	4.6 Disable Device from responding to MMIO/IO Port addresses	436	Disable Device from responding to MMIO/IO Port addresses
491	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~	437	--------------------------------------------------------
492	io_unmap() MMIO or IO Port resources and then call pci_disable_device().	438	io_unmap() MMIO or IO Port resources and then call pci_disable_device().
493	This is the symmetric opposite of pci_enable_device().	439	This is the symmetric opposite of pci_enable_device().
494	Do not access device registers after calling pci_disable_device().	440	Do not access device registers after calling pci_disable_device().
495		441
496		442
497	4.7 Release MMIO/IO Port Resource(s)	443	Release MMIO/IO Port Resource(s)
498	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~	444	--------------------------------
499	Call pci_release_region() to mark the MMIO or IO Port range as available.	445	Call pci_release_region() to mark the MMIO or IO Port range as available.
500	Failure to do so usually results in the inability to reload the driver.	446	Failure to do so usually results in the inability to reload the driver.
501		447
502		448
		449	How to access PCI config space
		450	==============================
503		451
504	5. How to access PCI config space	452	You can use `pci_(read\|write)_config_(byte\|word\|dword)` to access the config
505	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~	453	space of a device represented by `struct pci_dev *`. All these functions return
506		454	0 when successful or an error code (`PCIBIOS_...`) which can be translated to a
507	You can use pci_(read\|write)_config_(byte\|word\|dword) to access the config	455	text string by pcibios_strerror. Most drivers expect that accesses to valid PCI
508	space of a device represented by struct pci_dev *. All these functions return 0
509	when successful or an error code (PCIBIOS_...) which can be translated to a text
510	string by pcibios_strerror. Most drivers expect that accesses to valid PCI
511	devices don't fail.	456	devices don't fail.
512		457
513	If you don't have a struct pci_dev available, you can call	458	If you don't have a struct pci_dev available, you can call
514	pci_bus_(read\|write)_config_(byte\|word\|dword) to access a given device	459	`pci_bus_(read\|write)_config_(byte\|word\|dword)` to access a given device
515	and function on that bus.	460	and function on that bus.
516		461
517	If you access fields in the standard portion of the config header, please	462	If you access fields in the standard portion of the config header, please
@@ -522,10 +467,10 @@ pci_find_capability() for the particular capability and it will find the · 4 unmodified lines
522	corresponding register block for you.	467	corresponding register block for you.
523		468
524		469
		470	Other interesting functions
		471	===========================
525		472
526	6. Other interesting functions	473	============================= ================================================
527	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
528
529	pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,	474	pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,
530	bus and slot and number. If the device is	475	bus and slot and number. If the device is
531	found, its reference count is increased.	476	found, its reference count is increased.
@@ -539,11 +484,11 @@ pci_set_drvdata() Set private driver data pointer for a pci_dev · 7 unmodified lines
539	pci_get_drvdata() Return private driver data pointer for a pci_dev	484	pci_get_drvdata() Return private driver data pointer for a pci_dev
540	pci_set_mwi() Enable Memory-Write-Invalidate transactions.	485	pci_set_mwi() Enable Memory-Write-Invalidate transactions.
541	pci_clear_mwi() Disable Memory-Write-Invalidate transactions.	486	pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
		487	============================= ================================================
542		488
543		489
544		490	Miscellaneous hints
545	7. Miscellaneous hints	491	===================
546	~~~~~~~~~~~~~~~~~~~~~~
547		492
548	When displaying PCI device names to the user (for example when a driver wants	493	When displaying PCI device names to the user (for example when a driver wants
549	to tell the user what card has it found), please use pci_name(pci_dev).	494	to tell the user what card has it found), please use pci_name(pci_dev).
@@ -559,9 +504,8 @@ on the bus need to be capable of doing it, so this is something which needs · 9 unmodified lines
559	to be handled by platform and generic code, not individual drivers.	504	to be handled by platform and generic code, not individual drivers.
560		505
561		506
562		507	Vendor and device identifications
563	8. Vendor and device identifications	508	=================================
564	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
565		509
566	Do not add new device or vendor IDs to include/linux/pci_ids.h unless they	510	Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
567	are shared across multiple drivers. You can add private definitions in	511	are shared across multiple drivers. You can add private definitions in
@@ -575,28 +519,27 @@ There are mirrors of the pci.ids file at http://pciids.sourceforge.net/ · 7 unmodified lines
575	and https://github.com/pciutils/pciids.	519	and https://github.com/pciutils/pciids.
576		520
577		521
578		522	Obsolete functions
579	9. Obsolete functions	523	==================
580	~~~~~~~~~~~~~~~~~~~~~
581		524
582	There are several functions which you might come across when trying to	525	There are several functions which you might come across when trying to
583	port an old driver to the new PCI interface. They are no longer present	526	port an old driver to the new PCI interface. They are no longer present
584	in the kernel as they aren't compatible with hotplug or PCI domains or	527	in the kernel as they aren't compatible with hotplug or PCI domains or
585	having sane locking.	528	having sane locking.
586		529
		530	================= ===========================================
587	pci_find_device() Superseded by pci_get_device()	531	pci_find_device() Superseded by pci_get_device()
588	pci_find_subsys() Superseded by pci_get_subsys()	532	pci_find_subsys() Superseded by pci_get_subsys()
589	pci_find_slot() Superseded by pci_get_domain_bus_and_slot()	533	pci_find_slot() Superseded by pci_get_domain_bus_and_slot()
590	pci_get_slot() Superseded by pci_get_domain_bus_and_slot()	534	pci_get_slot() Superseded by pci_get_domain_bus_and_slot()
591		535	================= ===========================================
592		536
593	The alternative is the traditional PCI device driver that walks PCI	537	The alternative is the traditional PCI device driver that walks PCI
594	device lists. This is still possible but discouraged.	538	device lists. This is still possible but discouraged.
595		539
596		540
597		541	MMIO Space and "Write Posting"
598	10. MMIO Space and "Write Posting"	542	==============================
599	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
600		543
601	Converting a driver from using I/O Port space to using MMIO space	544	Converting a driver from using I/O Port space to using MMIO space
602	often requires some additional changes. Specifically, "write posting"	545	often requires some additional changes. Specifically, "write posting"
@@ -609,14 +552,14 @@ the CPU before the transaction has reached its destination. · 6 unmodified lines
609		552
610	Thus, timing sensitive code should add readl() where the CPU is	553	Thus, timing sensitive code should add readl() where the CPU is
611	expected to wait before doing other work. The classic "bit banging"	554	expected to wait before doing other work. The classic "bit banging"
612	sequence works fine for I/O Port space:	555	sequence works fine for I/O Port space::
613		556
614	for (i = 8; --i; val >>= 1) {	557	for (i = 8; --i; val >>= 1) {
615	outb(val & 1, ioport_reg); /* write bit */	558	outb(val & 1, ioport_reg); /* write bit */
616	udelay(10);	559	udelay(10);
617	}	560	}
618		561
619	The same sequence for MMIO space should be:	562	The same sequence for MMIO space should be::
620		563
621	for (i = 8; --i; val >>= 1) {	564	for (i = 8; --i; val >>= 1) {
622	writeb(val & 1, mmio_reg); /* write bit */	565	writeb(val & 1, mmio_reg); /* write bit */
@@ -633,4 +576,3 @@ handle the PCI master abort on all platforms if the PCI device is · 10 unmodified lines
633	expected to not respond to a readl(). Most x86 platforms will allow	576	expected to not respond to a readl(). Most x86 platforms will allow
634	MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage	577	MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage
635	(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail").	578	(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail").
636

include/linux/mod_devicetable.h+24−5

 #define PCI_ANY_ID (~0)
+/**
+ * struct pci_device_id - PCI device ID structure
+ * @vendor:		Vendor ID to match (or PCI_ANY_ID)
+ * @device:		Device ID to match (or PCI_ANY_ID)
+ * @subvendor:		Subsystem vendor ID to match (or PCI_ANY_ID)
+ * @subdevice:		Subsystem device ID to match (or PCI_ANY_ID)
+ * @class:		Device class, subclass, and "interface" to match.
+ *			See Appendix D of the PCI Local Bus Spec or
+ *			include/linux/pci_ids.h for a full list of classes.
+ *			Most drivers do not need to specify class/class_mask
+ *			as vendor/device is normally sufficient.
+ * @class_mask:		Limit which sub-fields of the class field are compared.
+ *			See drivers/scsi/sym53c8xx_2/ for example of usage.
+ * @driver_data:	Data private to the driver.
+ *			Most drivers don't need to use driver_data field.
+ *			Best practice is to use driver_data as an index
+ *			into a static list of equivalent device types,
+ *			instead of using it as a pointer.
+ */
 struct pci_device_id {
 	__u32 vendor, device;		/* Vendor and device ID or PCI_ANY_ID*/
 	__u32 subvendor, subdevice;	/* Subsystem ID's or PCI_ANY_ID */
 	__u16		match_flags;
 	__u16		manf_id;
-	__u16 		card_id;
+	__u16		card_id;
-	__u8  		func_id;
+	__u8		func_id;
 	/* for real multi-function devices */
-	__u8  		function;
+	__u8		function;
 	/* for pseudo multi-function devices */
-	__u8  		device_no;
+	__u8		device_no;
-	__u32 		prod_id_hash[4];
+	__u32		prod_id_hash[4];
 	/* not matched against in kernelspace */
 	const char *	prod_id[4];

include/linux/pci.h+47−1

@@ -151,6 +151,8 @@ static inline const char *pci_power_name(pci_power_t state) · 150 unmodified lines
151	#define PCI_PM_BUS_WAIT 50	151	#define PCI_PM_BUS_WAIT 50
152		152
153	/**	153	/**
		154	* typedef pci_channel_state_t
		155	*
154	* The pci_channel state describes connectivity between the CPU and	156	* The pci_channel state describes connectivity between the CPU and
155	* the PCI device. If some PCI bus between here and the PCI device	157	* the PCI device. If some PCI bus between here and the PCI device
156	* has crashed or locked up, this info is reflected here.	158	* has crashed or locked up, this info is reflected here.
@@ -775,6 +777,50 @@ struct pci_error_handlers { · 618 unmodified lines
775		777
776		778
777	struct module;	779	struct module;
		780
		781	/**
		782	* struct pci_driver - PCI driver structure
		783	* @node: List of driver structures.
		784	* @name: Driver name.
		785	* @id_table: Pointer to table of device IDs the driver is
		786	* interested in. Most drivers should export this
		787	* table using MODULE_DEVICE_TABLE(pci,...).
		788	* @probe: This probing function gets called (during execution
		789	* of pci_register_driver() for already existing
		790	* devices or later if a new device gets inserted) for
		791	* all PCI devices which match the ID table and are not
		792	* "owned" by the other drivers yet. This function gets
		793	* passed a "struct pci_dev \*" for each device whose
		794	* entry in the ID table matches the device. The probe
		795	* function returns zero when the driver chooses to
		796	* take "ownership" of the device or an error code
		797	* (negative number) otherwise.
		798	* The probe function always gets called from process
		799	* context, so it can sleep.
		800	* @remove: The remove() function gets called whenever a device
		801	* being handled by this driver is removed (either during
		802	* deregistration of the driver or when it's manually
		803	* pulled out of a hot-pluggable slot).
		804	* The remove function always gets called from process
		805	* context, so it can sleep.
		806	* @suspend: Put device into low power state.
		807	* @suspend_late: Put device into low power state.
		808	* @resume_early: Wake device from low power state.
		809	* @resume: Wake device from low power state.
		810	* (Please see Documentation/power/pci.txt for descriptions
		811	* of PCI Power Management and the related functions.)
		812	* @shutdown: Hook into reboot_notifier_list (kernel/sys.c).
		813	* Intended to stop any idling DMA operations.
		814	* Useful for enabling wake-on-lan (NIC) or changing
		815	* the power state of a device before reboot.
		816	* e.g. drivers/net/e100.c.
		817	* @sriov_configure: Optional driver callback to allow configuration of
		818	* number of VFs to enable via sysfs "sriov_numvfs" file.
		819	* @err_handler: See Documentation/PCI/pci-error-recovery.rst
		820	* @groups: Sysfs attribute groups.
		821	* @driver: Driver model structure.
		822	* @dynids: List of dynamically added device IDs.
		823	*/
778	struct pci_driver {	824	struct pci_driver {
779	struct list_head node;	825	struct list_head node;
780	const char *name;	826	const char *name;
@@ -2206,7 +2252,7 @@ static inline u8 pci_vpd_srdt_tag(const u8 *srdt) · 1425 unmodified lines
2206		2252
2207	/**	2253	/**
2208	* pci_vpd_info_field_size - Extracts the information field length	2254	* pci_vpd_info_field_size - Extracts the information field length
2209	* @lrdt: Pointer to the beginning of an information field header	2255	* @info_field: Pointer to the beginning of an information field header
2210	*	2256	*
2211	* Returns the extracted information field length.	2257	* Returns the extracted information field length.
2212	*/	2258	*/

Documentation: PCI: convert pci.txt to reST

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code