Linux-2.6.12-rc2v2.6.12-rc2

Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.

Let it rip!

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(&amp;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(&amp;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(&amp;dev_lock, flags)
+CPU A:  ...
+CPU A:  writel(newval, ring_ptr);
+CPU A:  spin_unlock_irqrestore(&amp;dev_lock, flags)
+        ...
+CPU B:  spin_lock_irqsave(&amp;dev_lock, flags)
+CPU B:  writel(newval2, ring_ptr);
+CPU B:  ...
+CPU B:  spin_unlock_irqrestore(&amp;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(&amp;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(&amp;dev_lock, flags)
+        ...
+CPU B:  spin_lock_irqsave(&amp;dev_lock, flags)
+CPU B:  writel(newval2, ring_ptr);
+CPU B:  ...
+CPU B:  mmiowb();
+CPU B:  spin_unlock_irqrestore(&amp;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>