Merge branch 'master'

82 files changed, 2047 insertions, 7078 deletions

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 433cf5e9ae0..5f7f7d7f77d 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -24,6 +24,8 @@ DMA-mapping.txt
 	- info for PCI drivers using DMA portably across all platforms.
 DocBook/
 	- directory with DocBook templates etc. for kernel documentation.
+HOWTO
+	- The process and procedures of how to do Linux kernel development.
 IO-mapping.txt
 	- how to access I/O mapped memory from within device drivers.
 IPMI.txt
@@ -256,6 +258,10 @@ specialix.txt
 	- info on hardware/driver for specialix IO8+ multiport serial card.
 spinlocks.txt
 	- info on using spinlocks to provide exclusive access in kernel.
+stable_api_nonsense.txt
+	- info on why the kernel does not have a stable in-kernel api or abi.
+stable_kernel_rules.txt
+	- rules and procedures for the -stable kernel releases.
 stallion.txt
 	- info on using the Stallion multiport serial driver.
 svga.txt
diff --git a/Documentation/HOWTO b/Documentation/HOWTO
new file mode 100644
index 00000000000..6c9e746267d
--- /dev/null
+++ b/Documentation/HOWTO
@@ -0,0 +1,618 @@
+HOWTO do Linux kernel development
+---------------------------------
+
+This is the be-all, end-all document on this topic.  It contains
+instructions on how to become a Linux kernel developer and how to learn
+to work with the Linux kernel development community.  It tries to not
+contain anything related to the technical aspects of kernel programming,
+but will help point you in the right direction for that.
+
+If anything in this document becomes out of date, please send in patches
+to the maintainer of this file, who is listed at the bottom of the
+document.
+
+
+Introduction
+------------
+
+So, you want to learn how to become a Linux kernel developer?  Or you
+have been told by your manager, "Go write a Linux driver for this
+device."  This document's goal is to teach you everything you need to
+know to achieve this by describing the process you need to go through,
+and hints on how to work with the community.  It will also try to
+explain some of the reasons why the community works like it does.
+
+The kernel is written mostly in C, with some architecture-dependent
+parts written in assembly. A good understanding of C is required for
+kernel development.  Assembly (any architecture) is not required unless
+you plan to do low-level development for that architecture.  Though they
+are not a good substitute for a solid C education and/or years of
+experience, the following books are good for, if anything, reference:
+ - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
+ - "Practical C Programming" by Steve Oualline [O'Reilly]
+
+The kernel is written using GNU C and the GNU toolchain.  While it
+adheres to the ISO C89 standard, it uses a number of extensions that are
+not featured in the standard.  The kernel is a freestanding C
+environment, with no reliance on the standard C library, so some
+portions of the C standard are not supported.  Arbitrary long long
+divisions and floating point are not allowed.  It can sometimes be
+difficult to understand the assumptions the kernel has on the toolchain
+and the extensions that it uses, and unfortunately there is no
+definitive reference for them.  Please check the gcc info pages (`info
+gcc`) for some information on them.
+
+Please remember that you are trying to learn how to work with the
+existing development community.  It is a diverse group of people, with
+high standards for coding, style and procedure.  These standards have
+been created over time based on what they have found to work best for
+such a large and geographically dispersed team.  Try to learn as much as
+possible about these standards ahead of time, as they are well
+documented; do not expect people to adapt to you or your company's way
+of doing things.
+
+
+Legal Issues
+------------
+
+The Linux kernel source code is released under the GPL.  Please see the
+file, COPYING, in the main directory of the source tree, for details on
+the license.  If you have further questions about the license, please
+contact a lawyer, and do not ask on the Linux kernel mailing list.  The
+people on the mailing lists are not lawyers, and you should not rely on
+their statements on legal matters.
+
+For common questions and answers about the GPL, please see:
+	http://www.gnu.org/licenses/gpl-faq.html
+
+
+Documentation
+------------
+
+The Linux kernel source tree has a large range of documents that are
+invaluable for learning how to interact with the kernel community.  When
+new features are added to the kernel, it is recommended that new
+documentation files are also added which explain how to use the feature.
+When a kernel change causes the interface that the kernel exposes to
+userspace to change, it is recommended that you send the information or
+a patch to the manual pages explaining the change to the manual pages
+maintainer at mtk-manpages@gmx.net.
+
+Here is a list of files that are in the kernel source tree that are
+required reading:
+  README
+    This file gives a short background on the Linux kernel and describes
+    what is necessary to do to configure and build the kernel.  People
+    who are new to the kernel should start here.
+
+  Documentation/Changes
+    This file gives a list of the minimum levels of various software
+    packages that are necessary to build and run the kernel
+    successfully.
+
+  Documentation/CodingStyle
+    This describes the Linux kernel coding style, and some of the
+    rationale behind it. All new code is expected to follow the
+    guidelines in this document. Most maintainers will only accept
+    patches if these rules are followed, and many people will only
+    review code if it is in the proper style.
+
+  Documentation/SubmittingPatches
+  Documentation/SubmittingDrivers
+    These files describe in explicit detail how to successfully create
+    and send a patch, including (but not limited to):
+       - Email contents
+       - Email format
+       - Who to send it to
+    Following these rules will not guarantee success (as all patches are
+    subject to scrutiny for content and style), but not following them
+    will almost always prevent it.
+
+    Other excellent descriptions of how to create patches properly are:
+	"The Perfect Patch"
+		http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
+	"Linux kernel patch submission format"
+		http://linux.yyz.us/patch-format.html
+
+  Documentation/stable_api_nonsense.txt
+    This file describes the rationale behind the conscious decision to
+    not have a stable API within the kernel, including things like:
+      - Subsystem shim-layers (for compatibility?)
+      - Driver portability between Operating Systems.
+      - Mitigating rapid change within the kernel source tree (or
+	preventing rapid change)
+    This document is crucial for understanding the Linux development
+    philosophy and is very important for people moving to Linux from
+    development on other Operating Systems.
+
+  Documentation/SecurityBugs
+    If you feel you have found a security problem in the Linux kernel,
+    please follow the steps in this document to help notify the kernel
+    developers, and help solve the issue.
+
+  Documentation/ManagementStyle
+    This document describes how Linux kernel maintainers operate and the
+    shared ethos behind their methodologies.  This is important reading
+    for anyone new to kernel development (or anyone simply curious about
+    it), as it resolves a lot of common misconceptions and confusion
+    about the unique behavior of kernel maintainers.
+
+  Documentation/stable_kernel_rules.txt
+    This file describes the rules on how the stable kernel releases
+    happen, and what to do if you want to get a change into one of these
+    releases.
+
+  Documentation/kernel-docs.txt
+    A list of external documentation that pertains to kernel
+    development.  Please consult this list if you do not find what you
+    are looking for within the in-kernel documentation.
+
+  Documentation/applying-patches.txt
+    A good introduction describing exactly what a patch is and how to
+    apply it to the different development branches of the kernel.
+
+The kernel also has a large number of documents that can be
+automatically generated from the source code itself.  This includes a
+full description of the in-kernel API, and rules on how to handle
+locking properly.  The documents will be created in the
+Documentation/DocBook/ directory and can be generated as PDF,
+Postscript, HTML, and man pages by running:
+	make pdfdocs
+	make psdocs
+	make htmldocs
+	make mandocs
+respectively from the main kernel source directory.
+
+
+Becoming A Kernel Developer
+---------------------------
+
+If you do not know anything about Linux kernel development, you should
+look at the Linux KernelNewbies project:
+	http://kernelnewbies.org
+It consists of a helpful mailing list where you can ask almost any type
+of basic kernel development question (make sure to search the archives
+first, before asking something that has already been answered in the
+past.)  It also has an IRC channel that you can use to ask questions in
+real-time, and a lot of helpful documentation that is useful for
+learning about Linux kernel development.
+
+The website has basic information about code organization, subsystems,
+and current projects (both in-tree and out-of-tree). It also describes
+some basic logistical information, like how to compile a kernel and
+apply a patch.
+
+If you do not know where you want to start, but you want to look for
+some task to start doing to join into the kernel development community,
+go to the Linux Kernel Janitor's project:
+	http://janitor.kernelnewbies.org/
+It is a great place to start.  It describes a list of relatively simple
+problems that need to be cleaned up and fixed within the Linux kernel
+source tree.  Working with the developers in charge of this project, you
+will learn the basics of getting your patch into the Linux kernel tree,
+and possibly be pointed in the direction of what to go work on next, if
+you do not already have an idea.
+
+If you already have a chunk of code that you want to put into the kernel
+tree, but need some help getting it in the proper form, the
+kernel-mentors project was created to help you out with this.  It is a
+mailing list, and can be found at:
+	http://selenic.com/mailman/listinfo/kernel-mentors
+
+Before making any actual modifications to the Linux kernel code, it is
+imperative to understand how the code in question works.  For this
+purpose, nothing is better than reading through it directly (most tricky
+bits are commented well), perhaps even with the help of specialized
+tools.  One such tool that is particularly recommended is the Linux
+Cross-Reference project, which is able to present source code in a
+self-referential, indexed webpage format. An excellent up-to-date
+repository of the kernel code may be found at:
+	http://sosdg.org/~coywolf/lxr/
+
+
+The development process
+-----------------------
+
+Linux kernel development process currently consists of a few different
+main kernel "branches" and lots of different subsystem-specific kernel
+branches.  These different branches are:
+  - main 2.6.x kernel tree
+  - 2.6.x.y -stable kernel tree
+  - 2.6.x -git kernel patches
+  - 2.6.x -mm kernel patches
+  - subsystem specific kernel trees and patches
+
+2.6.x kernel tree
+-----------------
+2.6.x kernels are maintained by Linus Torvalds, and can be found on
+kernel.org in the pub/linux/kernel/v2.6/ directory.  Its development
+process is as follows:
+  - As soon as a new kernel is released a two weeks window is open,
+    during this period of time maintainers can submit big diffs to
+    Linus, usually the patches that have already been included in the
+    -mm kernel for a few weeks.  The preferred way to submit big changes
+    is using git (the kernel's source management tool, more information
+    can be found at http://git.or.cz/) but plain patches are also just
+    fine.
+  - After two weeks a -rc1 kernel is released it is now possible to push
+    only patches that do not include new features that could affect the
+    stability of the whole kernel.  Please note that a whole new driver
+    (or filesystem) might be accepted after -rc1 because there is no
+    risk of causing regressions with such a change as long as the change
+    is self-contained and does not affect areas outside of the code that
+    is being added.  git can be used to send patches to Linus after -rc1
+    is released, but the patches need to also be sent to a public
+    mailing list for review.
+  - A new -rc is released whenever Linus deems the current git tree to
+    be in a reasonably sane state adequate for testing.  The goal is to
+    release a new -rc kernel every week.
+  - Process continues until the kernel is considered "ready", the
+    process should last around 6 weeks.
+
+It is worth mentioning what Andrew Morton wrote on the linux-kernel
+mailing list about kernel releases:
+	"Nobody knows when a kernel will be released, because it's
+	released according to perceived bug status, not according to a
+	preconceived timeline."
+
+2.6.x.y -stable kernel tree
+---------------------------
+Kernels with 4 digit versions are -stable kernels. They contain
+relatively small and critical fixes for security problems or significant
+regressions discovered in a given 2.6.x kernel.
+
+This is the recommended branch for users who want the most recent stable
+kernel and are not interested in helping test development/experimental
+versions.
+
+If no 2.6.x.y kernel is available, then the highest numbered 2.6.x
+kernel is the current stable kernel.
+
+2.6.x.y are maintained by the "stable" team <stable@kernel.org>, and are
+released almost every other week.
+
+The file Documentation/stable_kernel_rules.txt in the kernel tree
+documents what kinds of changes are acceptable for the -stable tree, and
+how the release process works.
+
+2.6.x -git patches
+------------------
+These are daily snapshots of Linus' kernel tree which are managed in a
+git repository (hence the name.) These patches are usually released
+daily and represent the current state of Linus' tree.  They are more
+experimental than -rc kernels since they are generated automatically
+without even a cursory glance to see if they are sane.
+
+2.6.x -mm kernel patches
+------------------------
+These are experimental kernel patches released by Andrew Morton.  Andrew
+takes all of the different subsystem kernel trees and patches and mushes
+them together, along with a lot of patches that have been plucked from
+the linux-kernel mailing list.  This tree serves as a proving ground for
+new features and patches.  Once a patch has proved its worth in -mm for
+a while Andrew or the subsystem maintainer pushes it on to Linus for
+inclusion in mainline.
+
+It is heavily encouraged that all new patches get tested in the -mm tree
+before they are sent to Linus for inclusion in the main kernel tree.
+
+These kernels are not appropriate for use on systems that are supposed
+to be stable and they are more risky to run than any of the other
+branches.
+
+If you wish to help out with the kernel development process, please test
+and use these kernel releases and provide feedback to the linux-kernel
+mailing list if you have any problems, and if everything works properly.
+
+In addition to all the other experimental patches, these kernels usually
+also contain any changes in the mainline -git kernels available at the
+time of release.
+
+The -mm kernels are not released on a fixed schedule, but usually a few
+-mm kernels are released in between each -rc kernel (1 to 3 is common).
+
+Subsystem Specific kernel trees and patches
+-------------------------------------------
+A number of the different kernel subsystem developers expose their
+development trees so that others can see what is happening in the
+different areas of the kernel.  These trees are pulled into the -mm
+kernel releases as described above.
+
+Here is a list of some of the different kernel trees available:
+  git trees:
+    - Kbuild development tree, Sam Ravnborg <sam@ravnborg.org>
+	kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git
+
+    - ACPI development tree, Len Brown <len.brown@intel.com>
+	kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git
+
+    - Block development tree, Jens Axboe <axboe@suse.de>
+	kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git
+
+    - DRM