18a8a602fSJonathan Corbet.. Copyright 2001 Matthew Wilcox 28a8a602fSJonathan Corbet.. 38a8a602fSJonathan Corbet.. This documentation is free software; you can redistribute 48a8a602fSJonathan Corbet.. it and/or modify it under the terms of the GNU General Public 58a8a602fSJonathan Corbet.. License as published by the Free Software Foundation; either 68a8a602fSJonathan Corbet.. version 2 of the License, or (at your option) any later 78a8a602fSJonathan Corbet.. version. 88a8a602fSJonathan Corbet 98a8a602fSJonathan Corbet=============================== 108a8a602fSJonathan CorbetBus-Independent Device Accesses 118a8a602fSJonathan Corbet=============================== 128a8a602fSJonathan Corbet 138a8a602fSJonathan Corbet:Author: Matthew Wilcox 148a8a602fSJonathan Corbet:Author: Alan Cox 158a8a602fSJonathan Corbet 168a8a602fSJonathan CorbetIntroduction 178a8a602fSJonathan Corbet============ 188a8a602fSJonathan Corbet 198a8a602fSJonathan CorbetLinux provides an API which abstracts performing IO across all busses 208a8a602fSJonathan Corbetand devices, allowing device drivers to be written independently of bus 218a8a602fSJonathan Corbettype. 228a8a602fSJonathan Corbet 238a8a602fSJonathan CorbetMemory Mapped IO 248a8a602fSJonathan Corbet================ 258a8a602fSJonathan Corbet 268a8a602fSJonathan CorbetGetting Access to the Device 278a8a602fSJonathan Corbet---------------------------- 288a8a602fSJonathan Corbet 298a8a602fSJonathan CorbetThe most widely supported form of IO is memory mapped IO. That is, a 308a8a602fSJonathan Corbetpart of the CPU's address space is interpreted not as accesses to 318a8a602fSJonathan Corbetmemory, but as accesses to a device. Some architectures define devices 328a8a602fSJonathan Corbetto be at a fixed address, but most have some method of discovering 338a8a602fSJonathan Corbetdevices. The PCI bus walk is a good example of such a scheme. This 348a8a602fSJonathan Corbetdocument does not cover how to receive such an address, but assumes you 358a8a602fSJonathan Corbetare starting with one. Physical addresses are of type unsigned long. 368a8a602fSJonathan Corbet 378a8a602fSJonathan CorbetThis address should not be used directly. Instead, to get an address 388a8a602fSJonathan Corbetsuitable for passing to the accessor functions described below, you 398a8a602fSJonathan Corbetshould call :c:func:`ioremap()`. An address suitable for accessing 408a8a602fSJonathan Corbetthe device will be returned to you. 418a8a602fSJonathan Corbet 428a8a602fSJonathan CorbetAfter you've finished using the device (say, in your module's exit 438a8a602fSJonathan Corbetroutine), call :c:func:`iounmap()` in order to return the address 448a8a602fSJonathan Corbetspace to the kernel. Most architectures allocate new address space each 458a8a602fSJonathan Corbettime you call :c:func:`ioremap()`, and they can run out unless you 468a8a602fSJonathan Corbetcall :c:func:`iounmap()`. 478a8a602fSJonathan Corbet 488a8a602fSJonathan CorbetAccessing the device 498a8a602fSJonathan Corbet-------------------- 508a8a602fSJonathan Corbet 518a8a602fSJonathan CorbetThe part of the interface most used by drivers is reading and writing 528a8a602fSJonathan Corbetmemory-mapped registers on the device. Linux provides interfaces to read 538a8a602fSJonathan Corbetand write 8-bit, 16-bit, 32-bit and 64-bit quantities. Due to a 548a8a602fSJonathan Corbethistorical accident, these are named byte, word, long and quad accesses. 558a8a602fSJonathan CorbetBoth read and write accesses are supported; there is no prefetch support 568a8a602fSJonathan Corbetat this time. 578a8a602fSJonathan Corbet 588a8a602fSJonathan CorbetThe functions are named readb(), readw(), readl(), readq(), 598a8a602fSJonathan Corbetreadb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(), 608a8a602fSJonathan Corbetwriteb(), writew(), writel() and writeq(). 618a8a602fSJonathan Corbet 628a8a602fSJonathan CorbetSome devices (such as framebuffers) would like to use larger transfers than 638a8a602fSJonathan Corbet8 bytes at a time. For these devices, the :c:func:`memcpy_toio()`, 648a8a602fSJonathan Corbet:c:func:`memcpy_fromio()` and :c:func:`memset_io()` functions are 658a8a602fSJonathan Corbetprovided. Do not use memset or memcpy on IO addresses; they are not 668a8a602fSJonathan Corbetguaranteed to copy data in order. 678a8a602fSJonathan Corbet 688a8a602fSJonathan CorbetThe read and write functions are defined to be ordered. That is the 698a8a602fSJonathan Corbetcompiler is not permitted to reorder the I/O sequence. When the ordering 708a8a602fSJonathan Corbetcan be compiler optimised, you can use __readb() and friends to 718a8a602fSJonathan Corbetindicate the relaxed ordering. Use this with care. 728a8a602fSJonathan Corbet 738a8a602fSJonathan CorbetWhile the basic functions are defined to be synchronous with respect to 748a8a602fSJonathan Corbeteach other and ordered with respect to each other the busses the devices 758a8a602fSJonathan Corbetsit on may themselves have asynchronicity. In particular many authors 768a8a602fSJonathan Corbetare burned by the fact that PCI bus writes are posted asynchronously. A 778a8a602fSJonathan Corbetdriver author must issue a read from the same device to ensure that 788a8a602fSJonathan Corbetwrites have occurred in the specific cases the author cares. This kind 798a8a602fSJonathan Corbetof property cannot be hidden from driver writers in the API. In some 808a8a602fSJonathan Corbetcases, the read used to flush the device may be expected to fail (if the 818a8a602fSJonathan Corbetcard is resetting, for example). In that case, the read should be done 828a8a602fSJonathan Corbetfrom config space, which is guaranteed to soft-fail if the card doesn't 838a8a602fSJonathan Corbetrespond. 848a8a602fSJonathan Corbet 858a8a602fSJonathan CorbetThe following is an example of flushing a write to a device when the 868a8a602fSJonathan Corbetdriver would like to ensure the write's effects are visible prior to 878a8a602fSJonathan Corbetcontinuing execution:: 888a8a602fSJonathan Corbet 898a8a602fSJonathan Corbet static inline void 908a8a602fSJonathan Corbet qla1280_disable_intrs(struct scsi_qla_host *ha) 918a8a602fSJonathan Corbet { 928a8a602fSJonathan Corbet struct device_reg *reg; 938a8a602fSJonathan Corbet 948a8a602fSJonathan Corbet reg = ha->iobase; 958a8a602fSJonathan Corbet /* disable risc and host interrupts */ 968a8a602fSJonathan Corbet WRT_REG_WORD(®->ictrl, 0); 978a8a602fSJonathan Corbet /* 988a8a602fSJonathan Corbet * The following read will ensure that the above write 998a8a602fSJonathan Corbet * has been received by the device before we return from this 1008a8a602fSJonathan Corbet * function. 1018a8a602fSJonathan Corbet */ 1028a8a602fSJonathan Corbet RD_REG_WORD(®->ictrl); 1038a8a602fSJonathan Corbet ha->flags.ints_enabled = 0; 1048a8a602fSJonathan Corbet } 1058a8a602fSJonathan Corbet 1068a8a602fSJonathan CorbetIn addition to write posting, on some large multiprocessing systems 1078a8a602fSJonathan Corbet(e.g. SGI Challenge, Origin and Altix machines) posted writes won't be 1088a8a602fSJonathan Corbetstrongly ordered coming from different CPUs. Thus it's important to 1098a8a602fSJonathan Corbetproperly protect parts of your driver that do memory-mapped writes with 1108a8a602fSJonathan Corbetlocks and use the :c:func:`mmiowb()` to make sure they arrive in the 1118a8a602fSJonathan Corbetorder intended. Issuing a regular readX() will also ensure write ordering, 1128a8a602fSJonathan Corbetbut should only be used when the 1138a8a602fSJonathan Corbetdriver has to be sure that the write has actually arrived at the device 1148a8a602fSJonathan Corbet(not that it's simply ordered with respect to other writes), since a 1158a8a602fSJonathan Corbetfull readX() is a relatively expensive operation. 1168a8a602fSJonathan Corbet 1178a8a602fSJonathan CorbetGenerally, one should use :c:func:`mmiowb()` prior to releasing a spinlock 1188a8a602fSJonathan Corbetthat protects regions using :c:func:`writeb()` or similar functions that 1198a8a602fSJonathan Corbetaren't surrounded by readb() calls, which will ensure ordering 1208a8a602fSJonathan Corbetand flushing. The following pseudocode illustrates what might occur if 1218a8a602fSJonathan Corbetwrite ordering isn't guaranteed via :c:func:`mmiowb()` or one of the 1228a8a602fSJonathan CorbetreadX() functions:: 1238a8a602fSJonathan Corbet 1248a8a602fSJonathan Corbet CPU A: spin_lock_irqsave(&dev_lock, flags) 1258a8a602fSJonathan Corbet CPU A: ... 1268a8a602fSJonathan Corbet CPU A: writel(newval, ring_ptr); 1278a8a602fSJonathan Corbet CPU A: spin_unlock_irqrestore(&dev_lock, flags) 1288a8a602fSJonathan Corbet ... 1298a8a602fSJonathan Corbet CPU B: spin_lock_irqsave(&dev_lock, flags) 1308a8a602fSJonathan Corbet CPU B: writel(newval2, ring_ptr); 1318a8a602fSJonathan Corbet CPU B: ... 1328a8a602fSJonathan Corbet CPU B: spin_unlock_irqrestore(&dev_lock, flags) 1338a8a602fSJonathan Corbet 1348a8a602fSJonathan CorbetIn the case above, newval2 could be written to ring_ptr before newval. 1358a8a602fSJonathan CorbetFixing it is easy though:: 1368a8a602fSJonathan Corbet 1378a8a602fSJonathan Corbet CPU A: spin_lock_irqsave(&dev_lock, flags) 1388a8a602fSJonathan Corbet CPU A: ... 1398a8a602fSJonathan Corbet CPU A: writel(newval, ring_ptr); 1408a8a602fSJonathan Corbet CPU A: mmiowb(); /* ensure no other writes beat us to the device */ 1418a8a602fSJonathan Corbet CPU A: spin_unlock_irqrestore(&dev_lock, flags) 1428a8a602fSJonathan Corbet ... 1438a8a602fSJonathan Corbet CPU B: spin_lock_irqsave(&dev_lock, flags) 1448a8a602fSJonathan Corbet CPU B: writel(newval2, ring_ptr); 1458a8a602fSJonathan Corbet CPU B: ... 1468a8a602fSJonathan Corbet CPU B: mmiowb(); 1478a8a602fSJonathan Corbet CPU B: spin_unlock_irqrestore(&dev_lock, flags) 1488a8a602fSJonathan Corbet 1498a8a602fSJonathan CorbetSee tg3.c for a real world example of how to use :c:func:`mmiowb()` 1508a8a602fSJonathan Corbet 1518a8a602fSJonathan CorbetPCI ordering rules also guarantee that PIO read responses arrive after any 1528a8a602fSJonathan Corbetoutstanding DMA writes from that bus, since for some devices the result of 1538a8a602fSJonathan Corbeta readb() call may signal to the driver that a DMA transaction is 1548a8a602fSJonathan Corbetcomplete. In many cases, however, the driver may want to indicate that the 1558a8a602fSJonathan Corbetnext readb() call has no relation to any previous DMA writes 1568a8a602fSJonathan Corbetperformed by the device. The driver can use readb_relaxed() for 1578a8a602fSJonathan Corbetthese cases, although only some platforms will honor the relaxed 1588a8a602fSJonathan Corbetsemantics. Using the relaxed read functions will provide significant 1598a8a602fSJonathan Corbetperformance benefits on platforms that support it. The qla2xxx driver 1608a8a602fSJonathan Corbetprovides examples of how to use readX_relaxed(). In many cases, a majority 1618a8a602fSJonathan Corbetof the driver's readX() calls can safely be converted to readX_relaxed() 1628a8a602fSJonathan Corbetcalls, since only a few will indicate or depend on DMA completion. 1638a8a602fSJonathan Corbet 1648a8a602fSJonathan CorbetPort Space Accesses 1658a8a602fSJonathan Corbet=================== 1668a8a602fSJonathan Corbet 1678a8a602fSJonathan CorbetPort Space Explained 1688a8a602fSJonathan Corbet-------------------- 1698a8a602fSJonathan Corbet 1708a8a602fSJonathan CorbetAnother form of IO commonly supported is Port Space. This is a range of 1718a8a602fSJonathan Corbetaddresses separate to the normal memory address space. Access to these 1728a8a602fSJonathan Corbetaddresses is generally not as fast as accesses to the memory mapped 1738a8a602fSJonathan Corbetaddresses, and it also has a potentially smaller address space. 1748a8a602fSJonathan Corbet 1758a8a602fSJonathan CorbetUnlike memory mapped IO, no preparation is required to access port 1768a8a602fSJonathan Corbetspace. 1778a8a602fSJonathan Corbet 1788a8a602fSJonathan CorbetAccessing Port Space 1798a8a602fSJonathan Corbet-------------------- 1808a8a602fSJonathan Corbet 1818a8a602fSJonathan CorbetAccesses to this space are provided through a set of functions which 1828a8a602fSJonathan Corbetallow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and 1838a8a602fSJonathan Corbetlong. These functions are :c:func:`inb()`, :c:func:`inw()`, 1848a8a602fSJonathan Corbet:c:func:`inl()`, :c:func:`outb()`, :c:func:`outw()` and 1858a8a602fSJonathan Corbet:c:func:`outl()`. 1868a8a602fSJonathan Corbet 1878a8a602fSJonathan CorbetSome variants are provided for these functions. Some devices require 1888a8a602fSJonathan Corbetthat accesses to their ports are slowed down. This functionality is 1898a8a602fSJonathan Corbetprovided by appending a ``_p`` to the end of the function. 1908a8a602fSJonathan CorbetThere are also equivalents to memcpy. The :c:func:`ins()` and 1918a8a602fSJonathan Corbet:c:func:`outs()` functions copy bytes, words or longs to the given 1928a8a602fSJonathan Corbetport. 1938a8a602fSJonathan Corbet 1948a8a602fSJonathan CorbetPublic Functions Provided 1958a8a602fSJonathan Corbet========================= 1968a8a602fSJonathan Corbet 1978a8a602fSJonathan Corbet.. kernel-doc:: arch/x86/include/asm/io.h 1988a8a602fSJonathan Corbet :internal: 1998a8a602fSJonathan Corbet 2008a8a602fSJonathan Corbet.. kernel-doc:: lib/pci_iomap.c 2018a8a602fSJonathan Corbet :export: 202