diff options
Diffstat (limited to 'Documentation/DocBook/deviceiobook.tmpl')
| -rw-r--r-- | Documentation/DocBook/deviceiobook.tmpl | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/Documentation/DocBook/deviceiobook.tmpl b/Documentation/DocBook/deviceiobook.tmpl new file mode 100644 index 000000000000..6f41f2f5c6f6 --- /dev/null +++ b/Documentation/DocBook/deviceiobook.tmpl @@ -0,0 +1,341 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> + +<book id="DoingIO"> + <bookinfo> + <title>Bus-Independent Device Accesses</title> + + <authorgroup> + <author> + <firstname>Matthew</firstname> + <surname>Wilcox</surname> + <affiliation> + <address> + <email>matthew@wil.cx</email> + </address> + </affiliation> + </author> + </authorgroup> + + <authorgroup> + <author> + <firstname>Alan</firstname> + <surname>Cox</surname> + <affiliation> + <address> + <email>alan@redhat.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2001</year> + <holder>Matthew Wilcox</holder> + </copyright> + + <legalnotice> + <para> + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later + version. + </para> + + <para> + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + </para> + + <para> + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + </para> + + <para> + For more details see the file COPYING in the source + distribution of Linux. + </para> + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <para> + Linux provides an API which abstracts performing IO across all busses + and devices, allowing device drivers to be written independently of + bus type. + </para> + </chapter> + + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <para> + None. + </para> + </chapter> + + <chapter id="mmio"> + <title>Memory Mapped IO</title> + <sect1> + <title>Getting Access to the Device</title> + <para> + The most widely supported form of IO is memory mapped IO. + That is, a part of the CPU's address space is interpreted + not as accesses to memory, but as accesses to a device. Some + architectures define devices to be at a fixed address, but most + have some method of discovering devices. The PCI bus walk is a + good example of such a scheme. This document does not cover how + to receive such an address, but assumes you are starting with one. + Physical addresses are of type unsigned long. + </para> + + <para> + This address should not be used directly. Instead, to get an + address suitable for passing to the accessor functions described + below, you should call <function>ioremap</function>. + An address suitable for accessing the device will be returned to you. + </para> + + <para> + After you've finished using the device (say, in your module's + exit routine), call <function>iounmap</function> in order to return + the address space to the kernel. Most architectures allocate new + address space each time you call <function>ioremap</function>, and + they can run out unless you call <function>iounmap</function>. + </para> + </sect1> + + <sect1> + <title>Accessing the device</title> + <para> + The part of the interface most used by drivers is reading and + writing memory-mapped registers on the device. Linux provides + interfaces to read and write 8-bit, 16-bit, 32-bit and 64-bit + quantities. Due to a historical accident, these are named byte, + word, long and quad accesses. Both read and write accesses are + supported; there is no prefetch support at this time. + </para> + + <para> + The functions are named <function>readb</function>, + <function>readw</function>, <function>readl</function>, + <function>readq</function>, <function>readb_relaxed</function>, + <function>readw_relaxed</function>, <function>readl_relaxed</function>, + <function>readq_relaxed</function>, <function>writeb</function>, + <function>writew</function>, <function>writel</function> and + <function>writeq</function>. + </para> + + <para> + Some devices (such as framebuffers) would like to use larger + transfers than 8 bytes at a time. For these devices, the + <function>memcpy_toio</function>, <function>memcpy_fromio</function> + and <function>memset_io</function> functions are provided. + Do not use memset or memcpy on IO addresses; they + are not guaranteed to copy data in order. + </para> + + <para> + The read and write functions are defined to be ordered. That is the + compiler is not permitted to reorder the I/O sequence. When the + ordering can be compiler optimised, you can use <function> + __readb</function> and friends to indicate the relaxed ordering. Use + this with care. + </para> + + <para> + While the basic functions are defined to be synchronous with respect + to each other and ordered with respect to each other the busses the + devices sit on may themselves have asynchronicity. In particular many + authors are burned by the fact that PCI bus writes are posted + asynchronously. A driver author must issue a read from the same + device to ensure that writes have occurred in the specific cases the + author cares. This kind of property cannot be hidden from driver + writers in the API. In some cases, the read used to flush the device + may be expected to fail (if the card is resetting, for example). In + that case, the read should be done from config space, which is + guaranteed to soft-fail if the card doesn't respond. + </para> + + <para> + The following is an example of flushing a write to a device when + the driver would like to ensure the write's effects are visible prior + to continuing execution. + </para> + +<programlisting> +static inline void +qla1280_disable_intrs(struct scsi_qla_host *ha) +{ + struct device_reg *reg; + + reg = ha->iobase; + /* disable risc and host interrupts */ + WRT_REG_WORD(&reg->ictrl, 0); + /* + * The following read will ensure that the above write + * has been received by the device before we return from this + * function. + */ + RD_REG_WORD(&reg->ictrl); + ha->flags.ints_enabled = 0; +} +</programlisting> + + <para> + In addition to write posting, on some large multiprocessing systems + (e.g. SGI Challenge, Origin and Altix machines) posted writes won't + be strongly ordered coming from different CPUs. Thus it's important + to properly protect parts of your driver that do memory-mapped writes + with locks and use the <function>mmiowb</function> to make sure they + arrive in the order intended. Issuing a regular <function>readX + </function> will also ensure write ordering, but should only be used + when the driver has to be sure that the write has actually arrived + at the device (not that it's simply ordered with respect to other + writes), since a full <function>readX</function> is a relatively + expensive operation. + </para> + + <para> + Generally, one should use <function>mmiowb</function> prior to + releasing a spinlock that protects regions using <function>writeb + </function> or similar functions that aren't surrounded by <function> + readb</function> calls, which will ensure ordering and flushing. The + following pseudocode illustrates what might occur if write ordering + isn't guaranteed via <function>mmiowb</function> or one of the + <function>readX</function> functions. + </para> + +<programlisting> +CPU A: spin_lock_irqsave(&dev_lock, flags) +CPU A: ... +CPU A: writel(newval, ring_ptr); +CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... +CPU B: spin_lock_irqsave(&dev_lock, flags) +CPU B: writel(newval2, ring_ptr); +CPU B: ... +CPU B: spin_unlock_irqrestore(&dev_lock, flags) +</programlisting> + + <para> + In the case above, newval2 could be written to ring_ptr before + newval. Fixing it is easy though: + </para> + +<programlisting> +CPU A: spin_lock_irqsave(&dev_lock, flags) +CPU A: ... +CPU A: writel(newval, ring_ptr); +CPU A: mmiowb(); /* ensure no other writes beat us to the device */ +CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... +CPU B: spin_lock_irqsave(&dev_lock, flags) +CPU B: writel(newval2, ring_ptr); +CPU B: ... +CPU B: mmiowb(); +CPU B: spin_unlock_irqrestore(&dev_lock, flags) +</programlisting> + + <para> + See tg3.c for a real world example of how to use <function>mmiowb + </function> + </para> + + <para> + PCI ordering rules also guarantee that PIO read responses arrive + after any outstanding DMA writes from that bus, since for some devices + the result of a <function>readb</function> call may signal to the + driver that a DMA transaction is complete. In many cases, however, + the driver may want to indicate that the next + <function>readb</function> call has no relation to any previous DMA + writes performed by the device. The driver can use + <function>readb_relaxed</function> for these cases, although only + some platforms will honor the relaxed semantics. Using the relaxed + read functions will provide significant performance benefits on + platforms that support it. The qla2xxx driver provides examples + of how to use <function>readX_relaxed</function>. In many cases, + a majority of the driver's <function>readX</function> calls can + safely be converted to <function>readX_relaxed</function> calls, since + only a few will indicate or depend on DMA completion. + </para> + </sect1> + + <sect1> + <title>ISA legacy functions</title> + <para> + On older kernels (2.2 and earlier) the ISA bus could be read or + written with these functions and without ioremap being used. This is + no longer true in Linux 2.4. A set of equivalent functions exist for + easy legacy driver porting. The functions available are prefixed + with 'isa_' and are <function>isa_readb</function>, + <function>isa_writeb</function>, <function>isa_readw</function>, + <function>isa_writew</function>, <function>isa_readl</function>, + <function>isa_writel</function>, <function>isa_memcpy_fromio</function> + and <function>isa_memcpy_toio</function> + </para> + <para> + These functions should not be used in new drivers, and will + eventually be going away. + </para> + </sect1> + + </chapter> + + <chapter> + <title>Port Space Accesses</title> + <sect1> + <title>Port Space Explained</title> + + <para> + Another form of IO commonly supported is Port Space. This is a + range of addresses separate to the normal memory address space. + Access to these addresses is generally not as fast as accesses + to the memory mapped addresses, and it also has a potentially + smaller address space. + </para> + + <para> + Unlike memory mapped IO, no preparation is required + to access port space. + </para> + + </sect1> + <sect1> + <title>Accessing Port Space</title> + <para> + Accesses to this space are provided through a set of functions + which allow 8-bit, 16-bit and 32-bit accesses; also + known as byte, word and long. These functions are + <function>inb</function>, <function>inw</function>, + <function>inl</function>, <function>outb</function>, + <function>outw</function> and <function>outl</function>. + </para> + + <para> + Some variants are provided for these functions. Some devices + require that accesses to their ports are slowed down. This + functionality is provided by appending a <function>_p</function> + to the end of the function. There are also equivalents to memcpy. + The <function>ins</function> and <function>outs</function> + functions copy bytes, words or longs to the given port. + </para> + </sect1> + + </chapter> + + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> +!Einclude/asm-i386/io.h + </chapter> + +</book> |