About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / PCI / pci.txt


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

1	
2				How To Write Linux PCI Drivers
3	
4			by Martin Mares <mj@ucw.cz> on 07-Feb-2000
5		updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006
6	
7	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8	The world of PCI is vast and full of (mostly unpleasant) surprises.
9	Since each CPU architecture implements different chip-sets and PCI devices
10	have different requirements (erm, "features"), the result is the PCI support
11	in the Linux kernel is not as trivial as one would wish. This short paper
12	tries to introduce all potential driver authors to Linux APIs for
13	PCI device drivers.
14	
15	A more complete resource is the third edition of "Linux Device Drivers"
16	by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
17	LDD3 is available for free (under Creative Commons License) from:
18	
19		http://lwn.net/Kernel/LDD3/
20	
21	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	
24	Please send questions/comments/patches about Linux PCI API to the
25	"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
26	
27	
28	
29	0. Structure of PCI drivers
30	~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
33	a new device, the driver with a matching "description" will be notified.
34	Details on this below.
35	
36	pci_register_driver() leaves most of the probing for devices to
37	the PCI layer and supports online insertion/removal of devices [thus
38	supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver].
39	pci_register_driver() call requires passing in a table of function
40	pointers and thus dictates the high level structure of a driver.
41	
42	Once the driver knows about a PCI device and takes ownership, the
43	driver generally needs to perform the following initialization:
44	
45		Enable the device
46		Request MMIO/IOP resources
47		Set the DMA mask size (for both coherent and streaming DMA)
48		Allocate and initialize shared control data (pci_allocate_coherent())
49		Access device configuration space (if needed)
50		Register IRQ handler (request_irq())
51		Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
52		Enable DMA/processing engines
53	
54	When done using the device, and perhaps the module needs to be unloaded,
55	the driver needs to take the follow steps:
56		Disable the device from generating IRQs
57		Release the IRQ (free_irq())
58		Stop all DMA activity
59		Release DMA buffers (both streaming and coherent)
60		Unregister from other subsystems (e.g. scsi or netdev)
61		Release MMIO/IOP resources
62		Disable the device
63	
64	Most of these topics are covered in the following sections.
65	For the rest look at LDD3 or <linux/pci.h> .
66	
67	If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
68	the PCI functions described below are defined as inline functions either
69	completely empty or just returning an appropriate error codes to avoid
70	lots of ifdefs in the drivers.
71	
72	
73	
74	1. pci_register_driver() call
75	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76	
77	PCI device drivers call pci_register_driver() during their
78	initialization with a pointer to a structure describing the 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	
132		subvendor,	Subsystem vendor and device ID to match (or PCI_ANY_ID)
133		subdevice,
134	
135		class		Device class, subclass, and "interface" to match.
136				See Appendix D of the PCI Local Bus Spec or
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	
150	
151	Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up
152	a pci_device_id table.
153	
154	New PCI IDs may be added to a device driver pci_ids table at runtime
155	as shown below:
156	
157	echo "vendor device subvendor subdevice class class_mask driver_data" > \
158	/sys/bus/pci/drivers/{driver}/new_id
159	
160	All fields are passed in as hexadecimal values (no leading 0x).
161	The vendor and device fields are mandatory, the others are optional. Users
162	need pass only as many optional fields as necessary:
163		o subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
164		o class and classmask fields default to 0
165		o driver_data defaults to 0UL.
166	
167	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
169	if all the pci_device_id entries have a non-zero driver_data value.
170	
171	Once added, the driver probe routine will be invoked for any unclaimed
172	PCI devices listed in its (newly updated) pci_ids list.
173	
174	When the driver exits, it just calls pci_unregister_driver() and the PCI layer
175	automatically calls the remove hook for all devices handled by the driver.
176	
177	
178	1.1 "Attributes" for driver functions/data
179	
180	Please mark the initialization and cleanup functions where appropriate
181	(the corresponding macros are defined in <linux/init.h>):
182	
183		__init		Initialization code. Thrown away after the driver
184				initializes.
185		__exit		Exit code. Ignored for non-modular drivers.
186	
187	Tips on when/where to use the above attributes:
188		o The module_init()/module_exit() functions (and all
189		  initialization functions called _only_ from these)
190		  should be marked __init/__exit.
191	
192		o Do not mark the struct pci_driver.
193	
194		o 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.
196	
197	
198	
199	2. How to find PCI devices manually
200	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201	
202	PCI drivers should have a really good reason for not using the
203	pci_register_driver() interface to search for PCI devices.
204	The main reason PCI devices are controlled by multiple drivers
205	is because one PCI device implements several different HW services.
206	E.g. combined serial/parallel port/floppy controller.
207	
208	A manual search may be performed using the following constructs:
209	
210	Searching by vendor and device ID:
211	
212		struct pci_dev *dev = NULL;
213		while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
214			configure_device(dev);
215	
216	Searching by class ID (iterate in a similar way):
217	
218		pci_get_class(CLASS_ID, dev)
219	
220	Searching by both vendor/device and subsystem vendor/device ID:
221	
222		pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
223	
224	You can use the constant PCI_ANY_ID as a wildcard replacement for
225	VENDOR_ID or DEVICE_ID.  This allows searching for any device from a
226	specific vendor, for example.
227	
228	These functions are hotplug-safe. They increment the reference count on
229	the pci_dev that they return. You must eventually (possibly at module unload)
230	decrement the reference count on these devices by calling pci_dev_put().
231	
232	
233	
234	3. Device Initialization Steps
235	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
236	
237	As noted in the introduction, most PCI drivers need the following steps
238	for device initialization:
239	
240		Enable the device
241		Request MMIO/IOP resources
242		Set the DMA mask size (for both coherent and streaming DMA)
243		Allocate and initialize shared control data (pci_allocate_coherent())
244		Access device configuration space (if needed)
245		Register IRQ handler (request_irq())
246		Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
247		Enable DMA/processing engines.
248	
249	The driver can access PCI config space registers at any time.
250	(Well, almost. When running BIST, config space can go away...but
251	that will just result in a PCI Bus Master Abort and config reads
252	will return garbage).
253	
254	
255	3.1 Enable the PCI device
256	~~~~~~~~~~~~~~~~~~~~~~~~~
257	Before touching any device registers, the driver needs to enable
258	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	
263	NOTE: pci_enable_device() can fail! Check the return value.
264	
265	[ OS BUG: we don't check resource allocations before enabling those
266	  resources. The sequence would make more sense if we called
267	  pci_request_resources() before calling pci_enable_device().
268	  Currently, the device drivers can't detect the bug when when two
269	  devices have been allocated the same range. This is not a common
270	  problem and unlikely to get fixed soon.
271	
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	
276	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
278	it's set to something bogus by the BIOS.  pci_clear_master() will
279	disable DMA by clearing the bus master bit.
280	
281	If the PCI device can use the PCI Memory-Write-Invalidate transaction,
282	call pci_set_mwi().  This enables the PCI_COMMAND bit for Mem-Wr-Inval
283	and also ensures that the cache line size register is set correctly.
284	Check the return value of pci_set_mwi() as not all architectures
285	or chip-sets may support Memory-Write-Invalidate.  Alternatively,
286	if Mem-Wr-Inval would be nice to have but is not required, call
287	pci_try_set_mwi() to have the system do its best effort at enabling
288	Mem-Wr-Inval.
289	
290	
291	3.2 Request MMIO/IOP resources
292	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
293	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
295	as the PCI "bus address" might have been remapped to a "host physical"
296	address by the arch/chip-set specific kernel support.
297	
298	See Documentation/io-mapping.txt for how to access device registers
299	or device memory.
300	
301	The device driver needs to call pci_request_region() to verify
302	no other device is already using the same address resource.
303	Conversely, drivers should call pci_release_region() AFTER
304	calling pci_disable_device().
305	The idea is to prevent two devices colliding on the same address range.
306	
307	[ See OS BUG comment above. Currently (2.6.19), The driver can only
308	  determine MMIO and IO Port resource availability _after_ calling
309	  pci_enable_device(). ]
310	
311	Generic flavors of pci_request_region() are request_mem_region()
312	(for MMIO ranges) and request_region() (for IO Port ranges).
313	Use these for address resources that are not described by "normal" PCI
314	BARs.
315	
316	Also see pci_request_selected_regions() below.
317	
318	
319	3.3 Set the DMA mask size
320	~~~~~~~~~~~~~~~~~~~~~~~~~
321	[ If anything below doesn't make sense, please refer to
322	  Documentation/DMA-API.txt. This section is just a reminder that
323	  drivers need to indicate DMA capabilities of the device and is not
324	  an authoritative source for DMA interfaces. ]
325	
326	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
328	32-bit bus master capability for streaming data need the driver
329	to "register" this capability by calling pci_set_dma_mask() with
330	appropriate parameters.  In general this allows more efficient DMA
331	on systems where System RAM exists above 4G _physical_ address.
332	
333	Drivers for all PCI-X and PCIe compliant devices must call
334	pci_set_dma_mask() as they are 64-bit DMA devices.
335	
336	Similarly, drivers must also "register" this capability if the device
337	can directly address "consistent memory" in System RAM above 4G physical
338	address by calling pci_set_consistent_dma_mask().
339	Again, this includes drivers for all PCI-X and PCIe compliant devices.
340	Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
341	64-bit DMA capable for payload ("streaming") data but not control
342	("consistent") data.
343	
344	
345	3.4 Setup shared control data
346	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
347	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
349	the DMA APIs. This section is just a reminder that it needs to be done
350	before enabling DMA on the device.
351	
352	
353	3.5 Initialize device registers
354	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
355	Some drivers will need specific "capability" fields programmed
356	or other "vendor specific" register initialized or reset.
357	E.g. clearing pending interrupts.
358	
359	
360	3.6 Register IRQ handler
361	~~~~~~~~~~~~~~~~~~~~~~~~
362	While calling request_irq() is the last step described here,
363	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.
365	
366	All interrupt handlers for IRQ lines should be registered with IRQF_SHARED
367	and use the devid to map IRQs to devices (remember that all PCI IRQ lines
368	can be shared).
369	
370	request_irq() will associate an interrupt handler and device handle
371	with an interrupt number. Historically interrupt numbers represent
372	IRQ lines which run from the PCI device to the Interrupt controller.
373	With MSI and MSI-X (more below) the interrupt number is a CPU "vector".
374	
375	request_irq() also enables the interrupt. Make sure the device is
376	quiesced and does not have any interrupts pending before registering
377	the interrupt handler.
378	
379	MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts"
380	which deliver interrupts to the CPU via a DMA write to a Local APIC.
381	The fundamental difference between MSI and MSI-X is how multiple
382	"vectors" get allocated. MSI requires contiguous blocks of vectors
383	while MSI-X can allocate several individual ones.
384	
385	MSI capability can be enabled by calling pci_alloc_irq_vectors() with the
386	PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This
387	causes the PCI support to program CPU vector data into the PCI device
388	capability registers. Many architectures, chip-sets, or BIOSes do NOT
389	support MSI or MSI-X and a call to pci_alloc_irq_vectors with just
390	the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always
391	specify PCI_IRQ_LEGACY as well.
392	
393	Drivers that have different interrupt handlers for MSI/MSI-X and
394	legacy INTx should chose the right one based on the msi_enabled
395	and msix_enabled flags in the pci_dev structure after calling
396	pci_alloc_irq_vectors.
397	
398	There are (at least) two really good reasons for using MSI:
399	1) MSI is an exclusive interrupt vector by definition.
400	   This means the interrupt handler doesn't have to verify
401	   its device caused the interrupt.
402	
403	2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
404	   to be visible to the host CPU(s) when the MSI is delivered. This
405	   is important for both data coherency and avoiding stale control data.
406	   This guarantee allows the driver to omit MMIO reads to flush
407	   the DMA stream.
408	
409	See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples
410	of MSI/MSI-X usage.
411	
412	
413	
414	4. PCI device shutdown
415	~~~~~~~~~~~~~~~~~~~~~~~
416	
417	When a PCI device driver is being unloaded, most of the following
418	steps need to be performed:
419	
420		Disable the device from generating IRQs
421		Release the IRQ (free_irq())
422		Stop all DMA activity
423		Release DMA buffers (both streaming and consistent)
424		Unregister from other subsystems (e.g. scsi or netdev)
425		Disable device from responding to MMIO/IO Port addresses
426		Release MMIO/IO Port resource(s)
427	
428	
429	4.1 Stop IRQs on the device
430	~~~~~~~~~~~~~~~~~~~~~~~~~~~
431	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)
433	the IRQ is shared with another device.
434	
435	When the shared IRQ handler is "unhooked", the remaining devices
436	using the same IRQ line will still need the IRQ enabled. Thus if the
437	"unhooked" device asserts IRQ line, the system will respond assuming
438	it was one of the remaining devices asserted the IRQ line. Since none
439	of the other devices will handle the IRQ, the system will "hang" until
440	it decides the IRQ isn't going to get handled and masks the IRQ (100,000
441	iterations later). Once the shared IRQ is masked, the remaining devices
442	will stop functioning properly. Not a nice situation.
443	
444	This is another reason to use MSI or MSI-X if it's available.
445	MSI and MSI-X are defined to be exclusive interrupts and thus
446	are not susceptible to the "screaming interrupt" problem.
447	
448	
449	4.2 Release the IRQ
450	~~~~~~~~~~~~~~~~~~~
451	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,
453	"unhook" the drivers IRQ handler from that IRQ, and finally release
454	the IRQ if no one else is using it.
455	
456	
457	4.3 Stop all DMA activity
458	~~~~~~~~~~~~~~~~~~~~~~~~~
459	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
461	corruption, hangs, and on some chip-sets a hard crash.
462	
463	Stopping DMA after stopping the IRQs can avoid races where the
464	IRQ handler might restart DMA engines.
465	
466	While this step sounds obvious and trivial, several "mature" drivers
467	didn't get this step right in the past.
468	
469	
470	4.4 Release DMA buffers
471	~~~~~~~~~~~~~~~~~~~~~~~
472	Once DMA is stopped, clean up streaming DMA first.
473	I.e. unmap data buffers and return buffers to "upstream"
474	owners if there is one.
475	
476	Then clean up "consistent" buffers which contain the control data.
477	
478	See Documentation/DMA-API.txt for details on unmapping interfaces.
479	
480	
481	4.5 Unregister from other subsystems
482	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
483	Most low level PCI device drivers support some other subsystem
484	like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
485	driver isn't losing resources from that other subsystem.
486	If this happens, typically the symptom is an Oops (panic) when
487	the subsystem attempts to call into a driver that has been unloaded.
488	
489	
490	4.6 Disable Device from responding to MMIO/IO Port addresses
491	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
492	io_unmap() MMIO or IO Port resources and then call pci_disable_device().
493	This is the symmetric opposite of pci_enable_device().
494	Do not access device registers after calling pci_disable_device().
495	
496	
497	4.7 Release MMIO/IO Port Resource(s)
498	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
499	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.
501	
502	
503	
504	5. How to access PCI config space
505	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
506	
507	You can use pci_(read|write)_config_(byte|word|dword) to access the config
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.
512	
513	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
515	and function on that bus.
516	
517	If you access fields in the standard portion of the config header, please
518	use symbolic names of locations and bits declared in <linux/pci.h>.
519	
520	If you need to access Extended PCI Capability registers, just call
521	pci_find_capability() for the particular capability and it will find the
522	corresponding register block for you.
523	
524	
525	
526	6. Other interesting functions
527	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
528	
529	pci_get_domain_bus_and_slot()	Find pci_dev corresponding to given domain,
530					bus and slot and number. If the device is
531					found, its reference count is increased.
532	pci_set_power_state()		Set PCI Power Management state (0=D0 ... 3=D3)
533	pci_find_capability()		Find specified capability in device's capability
534					list.
535	pci_resource_start()		Returns bus start address for a given PCI region
536	pci_resource_end()		Returns bus end address for a given PCI region
537	pci_resource_len()		Returns the byte length of a PCI region
538	pci_set_drvdata()		Set private driver data pointer for a pci_dev
539	pci_get_drvdata()		Return private driver data pointer for a pci_dev
540	pci_set_mwi()			Enable Memory-Write-Invalidate transactions.
541	pci_clear_mwi()			Disable Memory-Write-Invalidate transactions.
542	
543	
544	
545	7. Miscellaneous hints
546	~~~~~~~~~~~~~~~~~~~~~~
547	
548	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).
550	
551	Always refer to the PCI devices by a pointer to the pci_dev structure.
552	All PCI layer functions use this identification and it's the only
553	reasonable one. Don't use bus/slot/function numbers except for very
554	special purposes -- on systems with multiple primary buses their semantics
555	can be pretty complex.
556	
557	Don't try to turn on Fast Back to Back writes in your driver.  All devices
558	on the bus need to be capable of doing it, so this is something which needs
559	to be handled by platform and generic code, not individual drivers.
560	
561	
562	
563	8. Vendor and device identifications
564	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
565	
566	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
568	your driver if they're helpful, or just use plain hex constants.
569	
570	The device IDs are arbitrary hex numbers (vendor controlled) and normally used
571	only in a single location, the pci_device_id table.
572	
573	Please DO submit new vendor/device IDs to http://pci-ids.ucw.cz/.
574	There are mirrors of the pci.ids file at http://pciids.sourceforge.net/
575	and https://github.com/pciutils/pciids.
576	
577	
578	
579	9. Obsolete functions
580	~~~~~~~~~~~~~~~~~~~~~
581	
582	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
584	in the kernel as they aren't compatible with hotplug or PCI domains or
585	having sane locking.
586	
587	pci_find_device()	Superseded by pci_get_device()
588	pci_find_subsys()	Superseded by pci_get_subsys()
589	pci_find_slot()		Superseded by pci_get_domain_bus_and_slot()
590	pci_get_slot()		Superseded by pci_get_domain_bus_and_slot()
591	
592	
593	The alternative is the traditional PCI device driver that walks PCI
594	device lists. This is still possible but discouraged.
595	
596	
597	
598	10. MMIO Space and "Write Posting"
599	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
600	
601	Converting a driver from using I/O Port space to using MMIO space
602	often requires some additional changes. Specifically, "write posting"
603	needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
604	already do this. I/O Port space guarantees write transactions reach the PCI
605	device before the CPU can continue. Writes to MMIO space allow the CPU
606	to continue before the transaction reaches the PCI device. HW weenies
607	call this "Write Posting" because the write completion is "posted" to
608	the CPU before the transaction has reached its destination.
609	
610	Thus, timing sensitive code should add readl() where the CPU is
611	expected to wait before doing other work.  The classic "bit banging"
612	sequence works fine for I/O Port space:
613	
614	       for (i = 8; --i; val >>= 1) {
615	               outb(val & 1, ioport_reg);      /* write bit */
616	               udelay(10);
617	       }
618	
619	The same sequence for MMIO space should be:
620	
621	       for (i = 8; --i; val >>= 1) {
622	               writeb(val & 1, mmio_reg);      /* write bit */
623	               readb(safe_mmio_reg);           /* flush posted write */
624	               udelay(10);
625	       }
626	
627	It is important that "safe_mmio_reg" not have any side effects that
628	interferes with the correct operation of the device.
629	
630	Another case to watch out for is when resetting a PCI device. Use PCI
631	Configuration space reads to flush the writel(). This will gracefully
632	handle the PCI master abort on all platforms if the PCI device is
633	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
635	(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail").
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog