Manual merge with Linus

59 files changed, 4185 insertions, 725 deletions

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index f28a24e0279b..f6de52b01059 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -46,6 +46,8 @@ SubmittingPatches
 	- procedure to get a source patch included into the kernel tree.
 VGA-softcursor.txt
 	- how to change your VGA cursor from a blinking underscore.
+applying-patches.txt
+	- description of various trees and how to apply their patches.
 arm/
 	- directory with info about Linux on the ARM architecture.
 basic_profiling.txt
diff --git a/Documentation/DMA-ISA-LPC.txt b/Documentation/DMA-ISA-LPC.txt
new file mode 100644
index 000000000000..705f6be92bdb
--- /dev/null
+++ b/Documentation/DMA-ISA-LPC.txt
@@ -0,0 +1,151 @@
+                        DMA with ISA and LPC devices
+                        ============================
+
+                      Pierre Ossman <drzeus@drzeus.cx>
+
+This document describes how to do DMA transfers using the old ISA DMA
+controller. Even though ISA is more or less dead today the LPC bus
+uses the same DMA system so it will be around for quite some time.
+
+Part I - Headers and dependencies
+---------------------------------
+
+To do ISA style DMA you need to include two headers:
+
+#include <linux/dma-mapping.h>
+#include <asm/dma.h>
+
+The first is the generic DMA API used to convert virtual addresses to
+physical addresses (see Documentation/DMA-API.txt for details).
+
+The second contains the routines specific to ISA DMA transfers. Since
+this is not present on all platforms make sure you construct your
+Kconfig to be dependent on ISA_DMA_API (not ISA) so that nobody tries
+to build your driver on unsupported platforms.
+
+Part II - Buffer allocation
+---------------------------
+
+The ISA DMA controller has some very strict requirements on which
+memory it can access so extra care must be taken when allocating
+buffers.
+
+(You usually need a special buffer for DMA transfers instead of
+transferring directly to and from your normal data structures.)
+
+The DMA-able address space is the lowest 16 MB of _physical_ memory.
+Also the transfer block may not cross page boundaries (which are 64
+or 128 KiB depending on which channel you use).
+
+In order to allocate a piece of memory that satisfies all these
+requirements you pass the flag GFP_DMA to kmalloc.
+
+Unfortunately the memory available for ISA DMA is scarce so unless you
+allocate the memory during boot-up it's a good idea to also pass
+__GFP_REPEAT and __GFP_NOWARN to make the allocater try a bit harder.
+
+(This scarcity also means that you should allocate the buffer as
+early as possible and not release it until the driver is unloaded.)
+
+Part III - Address translation
+------------------------------
+
+To translate the virtual address to a physical use the normal DMA
+API. Do _not_ use isa_virt_to_phys() even though it does the same
+thing. The reason for this is that the function isa_virt_to_phys()
+will require a Kconfig dependency to ISA, not just ISA_DMA_API which
+is really all you need. Remember that even though the DMA controller
+has its origins in ISA it is used elsewhere.
+
+Note: x86_64 had a broken DMA API when it came to ISA but has since
+been fixed. If your arch has problems then fix the DMA API instead of
+reverting to the ISA functions.
+
+Part IV - Channels
+------------------
+
+A normal ISA DMA controller has 8 channels. The lower four are for
+8-bit transfers and the upper four are for 16-bit transfers.
+
+(Actually the DMA controller is really two separate controllers where
+channel 4 is used to give DMA access for the second controller (0-3).
+This means that of the four 16-bits channels only three are usable.)
+
+You allocate these in a similar fashion as all basic resources:
+
+extern int request_dma(unsigned int dmanr, const char * device_id);
+extern void free_dma(unsigned int dmanr);
+
+The ability to use 16-bit or 8-bit transfers is _not_ up to you as a
+driver author but depends on what the hardware supports. Check your
+specs or test different channels.
+
+Part V - Transfer data
+----------------------
+
+Now for the good stuff, the actual DMA transfer. :)
+
+Before you use any ISA DMA routines you need to claim the DMA lock
+using claim_dma_lock(). The reason is that some DMA operations are
+not atomic so only one driver may fiddle with the registers at a
+time.
+
+The first time you use the DMA controller you should call
+clear_dma_ff(). This clears an internal register in the DMA
+controller that is used for the non-atomic operations. As long as you
+(and everyone else) uses the locking functions then you only need to
+reset this once.
+
+Next, you tell the controller in which direction you intend to do the
+transfer using set_dma_mode(). Currently you have the options
+DMA_MODE_READ and DMA_MODE_WRITE.
+
+Set the address from where the transfer should start (this needs to
+be 16-bit aligned for 16-bit transfers) and how many bytes to
+transfer. Note that it's _bytes_. The DMA routines will do all the
+required translation to values that the DMA controller understands.
+
+The final step is enabling the DMA channel and releasing the DMA
+lock.
+
+Once the DMA transfer is finished (or timed out) you should disable
+the channel again. You should also check get_dma_residue() to make
+sure that all data has been transfered.
+
+Example:
+
+int flags, residue;
+
+flags = claim_dma_lock();
+
+clear_dma_ff();
+
+set_dma_mode(channel, DMA_MODE_WRITE);
+set_dma_addr(channel, phys_addr);
+set_dma_count(channel, num_bytes);
+
+dma_enable(channel);
+
+release_dma_lock(flags);
+
+while (!device_done());
+
+flags = claim_dma_lock();
+
+dma_disable(channel);
+
+residue = dma_get_residue(channel);
+if (residue != 0)
+	printk(KERN_ERR "driver: Incomplete DMA transfer!"
+		" %d bytes left!\n", residue);
+
+release_dma_lock(flags);
+
+Part VI - Suspend/resume
+------------------------
+
+It is the driver's responsibility to make sure that the machine isn't
+suspended while a DMA transfer is in progress. Also, all DMA settings
+are lost when the system suspends so if your driver relies on the DMA
+controller being in a certain state then you have to restore these
+registers upon resume.
diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl
index 49a9ef82d575..6367bba32d22 100644
--- a/Documentation/DocBook/kernel-hacking.tmpl
+++ b/Documentation/DocBook/kernel-hacking.tmpl
@@ -8,8 +8,7 @@
   
   <authorgroup>
    <author>
-    <firstname>Paul</firstname>
-    <othername>Rusty</othername>
+    <firstname>Rusty</firstname>
     <surname>Russell</surname>
     <affiliation>
      <address>
@@ -20,7 +19,7 @@
   </authorgroup>
 
   <copyright>
-   <year>2001</year>
+   <year>2005</year>
    <holder>Rusty Russell</holder>
   </copyright>
 
@@ -64,7 +63,7 @@
  <chapter id="introduction">
   <title>Introduction</title>
   <para>
-   Welcome, gentle reader, to Rusty's Unreliable Guide to Linux
+   Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux
    Kernel Hacking.  This document describes the common routines and
    general requirements for kernel code: its goal is to serve as a
    primer for Linux kernel development for experienced C
@@ -96,13 +95,13 @@
 
    <listitem>
     <para>
-     not associated with any process, serving a softirq, tasklet or bh;
+     not associated with any process, serving a softirq or tasklet;
     </para>
    </listitem>
 
    <listitem>
     <para>
-     running in kernel space, associated with a process;
+     running in kernel space, associated with a process (user context);
     </para>
    </listitem>
 
@@ -114,11 +113,12 @@
   </itemizedlist>
 
   <para>
-   There is a strict ordering between these: other than the last
-   category (userspace) each can only be pre-empted by those above.
-   For example, while a softirq is running on a CPU, no other
-   softirq will pre-empt it, but a hardware interrupt can.  However,
-   any other CPUs in the system execute independently.
+   There is an ordering between these.  The bottom two can preempt
+   each other, but above that is a strict hierarchy: each can only be
+   preempted by the ones above it.  For example, while a softirq is
+   running on a CPU, no other softirq will preempt it, but a hardware
+   interrupt can.  However, any other CPUs in the system execute
+   independently.
   </para>
 
   <para>
@@ -130,10 +130,10 @@
    <title>User Context</title>
 
    <para>
-    User context is when you are coming in from a system call or
-    other trap: you can sleep, and you own the CPU (except for
-    interrupts) until you call <function>schedule()</function>.  
-    In other words, user context (unlike userspace) is not pre-emptable.
+    User context is when you are coming in from a system call or other
+    trap: like userspace, you can be preempted by more important tasks
+    and by interrupts.  You can sleep, by calling
+    <function>schedule()</function>.
    </para>
 
    <note>
@@ -153,7 +153,7 @@
 
    <caution>
     <para>
-     Beware that if you have interrupts or bottom halves disabled 
+     Beware that if you have preemption or softirqs disabled
      (see below), <function>in_interrupt()</function> will return a 
      false positive.
     </para>
@@ -168,10 +168,10 @@
     <hardware>keyboard</hardware> are examples of real
     hardware which produce interrupts at any time.  The kernel runs
     interrupt handlers, which services the hardware.  The kernel
-    guarantees that this handler is never re-entered: if another
+    guarantees that this handler is never re-entered: if the same
     interrupt arrives, it is queued (or dropped).  Because it
     disables interrupts, this handler has to be fast: frequently it
-    simply acknowledges the interrupt, marks a `software interrupt'
+    simply acknowledges the interrupt, marks a 'software interrupt'
     for execution and exits.
    </para>
 
@@ -188,60 +188,52 @@
   </sect1>
 
   <sect1 id="basics-softirqs">
-   <title>Software Interrupt Context: Bottom Halves, Tasklets, softirqs</title>
+   <title>Software Interrupt Context: Softirqs and Tasklets</title>
 
    <para>
     Whenever a system call is about to return to userspace, or a
-    hardware interrupt handler exits, any `software interrupts'
+    hardware interrupt handler exits, any 'software interrupts'
     which are marked pending (usually by hardware interrupts) are
     run (<filename>kernel/softirq.c</filename>).
    </para>
 
    <para>
     Much of the real interrupt handling work is done here.  Early in
-    the transition to <acronym>SMP</acronym>, there were only `bottom 
+    the transition to <acronym>SMP</acronym>, there were only 'bottom
     halves' (BHs), which didn't take advantage of multiple CPUs.  Shortly 
     after we switched from wind-up computers made of match-sticks and snot,
-    we abandoned this limitation.
+    we abandoned this limitation and switched to 'softirqs'.
    </para>
 
    <para>
     <filename class="headerfile">include/linux/interrupt.h</filename> lists the
-    different BH's.  No matter how many CPUs you have, no two BHs will run at 
-    the same time. This made the transition to SMP simpler, but sucks hard for
-    scalable performance.  A very important bottom half is the timer
-    BH (<filename class="headerfile">include/linux/timer.h</filename>): you
-    can register to have it call functions for you in a given length of time.
+    different softirqs.  A very important softirq is the
+    timer softirq (<filename
+    class="headerfile">include/linux/timer.h</filename>): you can
+    register to have it call functions for you in a given length of
+    time.
    </para>
 
    <para>
-    2.3.43 introduced softirqs, and re-implemented the (now
-    deprecated) BHs underneath them.  Softirqs are fully-SMP
-    versions of BHs: they can run on as many CPUs at once as
-    required.  This means they need to deal with any races in shared
-    data using their own locks.  A bitmask is used to keep track of
-    which are enabled, so the 32 available softirqs should not be
-    used up lightly.  (<emphasis>Yes</emphasis>, people will
-    notice).
-   </para>
-
-   <para>
-    tasklets (<filename class="headerfile">include/linux/interrupt.h</filename>)
-    are like softirqs, except they are dynamically-registrable (meaning you 
-    can have as many as you want), and they also guarantee that any tasklet 
-    will only run on one CPU at any time, although different tasklets can 
-    run simultaneously (unlike different BHs).  
+    Softirqs are often a pain to deal with, since the same softirq
+    will run simultaneously on more than one CPU.  For this reason,
+    tasklets (<filename
+    class="headerfile">include/linux/interrupt.h</filename>) are more
+    often used: they are dynamically-registrable (meaning you can have
+    as many as you want), and they also guarantee that any tasklet
+    will only run on one CPU at any time, although different tasklets
+    can run simultaneously.
    </para>
    <caution>
     <para>
-     The name `tasklet' is misleading: they have nothing to do with `tasks', 
+     The name 'tasklet' is misleading: they have nothing to do with 'tasks',
      and probably more to do with some bad vodka Alexey Kuznetsov had at the 
      time.
     </para>
    </caution>
 
    <para>
-    You can tell you are in a softirq (or bottom half, or tasklet)
+    You can tell you are in a softirq (or tasklet)
     using the <function>in_softirq()</function> macro 
     (<filename class="headerfile">include/linux/interrupt.h</filename>).
    </para>
@@ -288,11 +280,10 @@
     <term>A rigid stack limit</term>
     <listitem>
      <para>
-      The kernel stack is about 6K in 2.2 (for most
-      architectures: it's about 14K on the Alpha), and shared
-      with interrupts so you can't use it all.  Avoid deep
-      recursion and huge local arrays on the stack (allocate
-      them dynamically instead).
+      Depending on configuration options the kernel stack is about 3K to 6K for most 32-bit architectures: it's
+      about 14K on most 64-bit archs, and often shared with interrupts
+      so you can't use it all.  Avoid deep recursion and huge local
+      arrays on the stack (allocate them dynamically instead).
      </para>
     </listitem>
    </varlistentry>
@@ -339,7 +330,7 @@ asmlinkage long sys_mycall(int arg)
 
   <para>
    If all your routine does is read or write some parameter, consider
-   implementing a <function>sysctl</function> interface instead.
+   implementing a <function>sysfs</function> interface instead.
   </para>
 
   <para>
@@ -417,7 +408,10 @@ cond_resched(); /* Will sleep */
   </para>
 
   <para>
-   You will eventually lock up your box if you break these rules.  
+   You should always compile your kernel
+   <symbol>CONFIG_DEBUG_SPINLOCK_SLEEP</symbol> on, and it will warn
+   you if you break these rules.  If you <emphasis>do</emphasis> break
+   the rules, you will eventually lock up your box.
   </para>
 
   <para>
@@ -515,8 +509,7 @@ printk(KERN_INFO "my ip: %d.%d.%d.%d\n", NIPQUAD(ipaddress));
       success).
      </para>
     </caution>
-    [Yes, this moronic interface makes me cringe.  Please submit a
-    patch and become my hero --RR.]
+    [Yes, this moronic interface makes me cringe.  The flamewar comes up every year or so. --RR.]
    </para>
    <para>
     The functions may sleep implicitly. This should never be called
@@ -587,10 +580,11 @@ printk(KERN_INFO "my ip: %d.%d.%d.%d\n", NIPQUAD(ipaddress));
    </variablelist>
 
    <para>
-    If you see a <errorname>kmem_grow: Called nonatomically from int
-    </errorname> warning message you called a memory allocation function
-    from interrupt context without <constant>GFP_ATOMIC</constant>.
-    You should really fix that.  Run, don't walk.
+    If you see a <errorname>sleeping function called from invalid
+    context</errorname> warning message, then maybe you called a
+    sleeping allocation function from interrupt context without
+    <constant>GFP_ATOMIC</constant>.  You should really fix that.
+    Run, don't walk.
    </para>
 
    <para>
@@ -639,16 +633,16 @@ printk(KERN_INFO "my ip: %d.%d.%d.%d\n", NIPQUAD(ipaddress));
   </sect1>
 
   <sect1 id="routines-udelay">
-   <title><function>udelay()</function>/<function>mdelay()</function>
+   <title><function>mdelay()</function>/<function>udelay()</function>
      <filename class="headerfile">include/asm/delay.h</filename>
      <filename class="headerfile">include/linux/delay.h</filename>
    </title>
 
    <para>
-    The <function>udelay()</function> function can be used for small pauses.
-    Do not use large values with <function>udelay()</function> as you risk
+    The <function>udelay()</function> and <function>ndelay()</function> functions can be used for small pauses.
+    Do not use large values with them as you risk
     overflow - the helper function <function>mdelay()</function> is useful
-    here, or even consider <function>schedule_timeout()</function>.
+    here, or consider <function>msleep()</function>.
    </para> 
   </sect1>
  
@@ -698,8 +692,8 @@ printk(KERN_INFO "my ip: %d.%d.%d.%d\n", NIPQUAD(ipaddress));
     These routines disable soft interrupts on the local CPU, and
     restore them.  They are reentrant; if soft interrupts were
     disabled before, they will still be disabled after this pair
-    of functions has been called.  They prevent softirqs, tasklets
-    and bottom halves from running on the current CPU.
+    of functions has been called.  They prevent softirqs and tasklets
+    from running on the current CPU.
    </para>
   </sect1>
 
@@ -708,10 +702,16 @@ printk(KERN_INFO "my ip: %d.%d.%d.%d\n", NIPQUAD(ipaddress));
     <filename class="headerfile">include/asm/smp.h</filename></title>
    
    <para>
-    <function>smp_processor_id()</function> returns the current
-    processor number, between 0 and <symbol>NR_CPUS</symbol> (the
-    maximum number of CPUs supported by Linux, currently 32).  These
-    values are not necessarily continuous.
+    <function>get_cpu()</function> disables preemption (so you won't
+    suddenly get moved to another CPU) and returns the current
+    processor number, between 0 and <symbol>NR_CPUS</symbol>.  Note
+    that the CPU numbers are not necessarily continuous.  You return
+    it again with <function>put_cpu()</function> when you are done.
+   </para>
+   <para>
+    If you know you cannot be preempted by another task (ie. you are
+    in interrupt context, or have preemption disabled) you can use
+    smp_processor_id().
    </para>
   </sect1>
 
@@ -722,19 +722,14 @@ printk(KERN_INFO "my ip: %d.%d.%d.%d\n", NIPQUAD(ipaddress));
    <para>
     After boot, the kernel frees up a special section; functions
     marked with <type>__init</type> and data structures marked with
-    <type>__initdata</type> are dropped after boot is complete (within
-    modules this directive is currently ignored).  <type>__exit</type>
+    <type>__initdata</type> are dropped after boot is complete: similarly
+    modules discard this memory after initialization.  <type>__exit</type>
     is used to declare a function which is only required on exit: the
     function will be dropped if this file is not compiled as a module.
     See the header file for use. Note that it makes no sense for a function
     marked with <type>__init</type> to be exported to modules with 
     <function>EXPORT_SYMBOL()</function> - this will break.
    </para>
-   <para>
-   Static data structures marked as <type>__initdata</type> must be initialised
-   (as opposed to ordinary static data which is zeroed BSS) and cannot be 
-   <type>const</type>.
-   </para> 
 
   </sect1>
 
@@ -762,9 +757,8 @@ printk(KERN_INFO "my ip: %d.%d.%d.%d\n", NIPQUAD(ipaddress));
    <para>
     The function can return a negative error number to cause
     module loading to fail (unfortunately, this has no effect if
-    the module is compiled into the kernel).  For modules, this is
-    called in user context, with interrupts enabled, and the
-    kernel lock held, so it can sleep.
+    the module is compiled into the kernel).  This function is
+    called in user context with interrupts enabled, so it can sleep.
    </para>
   </sect1>
   
@@ -779,6 +773,34 @@ printk(KERN_INFO "my ip: %d.%d.%d.%d\n", NIPQUAD(ipaddress));
     reached zero.  This function can also sleep, but cannot fail:
     everything must be cleaned up by the time it returns.
    </para>
+
+   <para>
+    Note that this macro is optional: if it is not present, your
+    module will not be removable (except for 'rmmod -f').
+   </para>
+  </sect1>
+
+  <sect1 id="routines-module-use-counters">
+   <title> <function>try_module_get()</function>/<function>module_put()</function>
+    <filename class="headerfile">include/linux/module.h</filename></title>
+
+   <para>
+    These manipulate the module usage count, to protect against
+    removal (a module also can't be removed if another module uses one
+    of its exported symbols: see below).  Before calling into module
+    code, you should call <function>try_module_get()</function> on