reorg for proper pci places

1 files changed, 89 insertions, 14 deletions

diff --git a/HOWTO b/HOWTO
index ccefde5191233..378566eea90cc 100644
--- a/HOWTO
+++ b/HOWTO
@@ -19,15 +19,36 @@ 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.
 
-What this document does not do, is teach you how to program.  There are
-plenty of good places to learn how to do this, but this is not such a
-place.
 
-First off, please remember that you are trying to learn how to work with
-the existing development community.  You should try to learn as much as
-possible ahead of time, and not expect people to adapt to you, or your
-company's way of doing things, no matter how important you feel your
-task is.
+The kernel is written mostly in C, with some architectural-dependent
+parts written in assembly. A good understanding of C is required to
+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, if anything for reference:
+
+"The C Programming Language" by Kernhigan and Ritchie [Prentice Hall]
+"Practical C Programming" by Steve Oualline [O'Reilly]
+"Programming the 80386" by Crawford and Gelsinger [Sybek]
+"UNIX Systems for Modern Architectures" by Curt Schimmel [Addison Wesley]
+
+The kernel is written using GNU C and the GNU toolchain. While it
+adheres to the ISO C99 (??) standard, it uses a number of extensions
+that are not featured in the standard. 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 very diverse group of people,
+with very high standards for coding, style, and procedure.  These
+procedures have been created over time based on what they have found to
+work best for such a large and geographically dispursed team.  Try to
+learn as much as possible about these procedures ahead of time, as they
+are well documented, and not expect people to adapt to you, or your
+company's way of doing things.
+
 
 
 Legal Issues
@@ -110,7 +131,7 @@ Becoming A Kernel Developer
 
 If you do not know anything about Linux kernel development, you should
 look at the Linux KernelNewbies project:
-	URL
+	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
@@ -118,11 +139,14 @@ past.)  It also has a 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 basic
+logistical information, like compiling a kernel and applying 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:
-	URL
+	http://janitor.kernelnewbies.org/
 It is a great place to start.  It describes a list of relatively simple
 tasks that need to be cleaned up and fixed within the Linux kernel
 source tree.  Working with the developers in charge of this project, you
@@ -135,19 +159,22 @@ If you already have a chunk of code that you want to have go 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:
-	URL
+	http://selenic.com/mailman/listinfo/kernel-mentors
 
 
 The development process
 -----------------------
 
+<TODO>
+
+
 Mailing lists
 -------------
 
 As some of the above documents describe, the majority of the core kernel
 developers participate on the Linux Kernel Mailing list.  Details on how
 to subscribe and unsubscribe from the list, can be found at:
-	URL
+	http://vger.kernel.org/vger-lists.html#linux-kernel
 There are archives of the mailing list on the web in many different
 places.  Please use a search engine to find these archives if you wish
 to research what has been discussed in the past.
@@ -157,6 +184,18 @@ mailing list where they do their development efforts.  See the
 MAINTAINERS file for a list of what these lists are, for the different
 groups.
 
+Many of the lists are hosted on kernel.org. Information on them can be
+found here:
+	http://vger.kernel.org/vger-lists.html
+
+Please remember to follow good behavioral habits when using the lists.
+Though a bit cheesy, the following URL has some simple guidelines for
+interacting with the list (or any list):
+	http://www.albion.com/netiquette/
+
+Above all, please remember to show respect to other subscribers.
+
+
 
 Working with the community
 --------------------------
@@ -184,6 +223,8 @@ do to try to avoid problems:
     - "Here's a 5000 line patch that..."
 
 
+
+
 Break your changes up
 ---------------------
 
@@ -196,13 +237,47 @@ you can receive feedback on what you are doing.  It also lets the
 community feel that you are working with them, and not simply using them
 as a dumping ground for your feature.
 
+The reasons for breaking things up are the following:
+
+1) Small patches increase the likelihood that your patches will be
+   applied, since they don't take much time or effort to verify for
+   correctness.  A 5 line patch can be applied by a maintainer with
+   barely a second glance. But, a 500 line patch may take hours to
+   review for correctness (the time it takes is exponentially
+   proportional to the size of the patch, or something).
+
+   Small patches also make it very easy to debug when something goes
+   wrong.  It's much easier to back out patches one by one, than it is
+   to dissect a very large patch after it's been applied (and broken
+   something).
+
+2) It's important not only to send small patches, but also to rewrite
+   and simplify (or simply re-order) patches before submitting them.
+
+Think of a teacher grading homework from a math student.  The teacher
+does not want to see the student's trials and errors before they came up
+with the solution. They want to see the cleanest, most elegant answer.
+The student knows this, and would never submit her intermediate work
+before the final solution.
+
+The same is true of kernel development. The maintainers and reviewers do
+not want to see the thought process behind the solution to the problem
+one is solving. They want to see a final, simple, elegant solution.
+
+Both of these things are sometimes very hard to do. It can take years
+to perfect these practices (if at all). It's a continuous process of
+improvement that requires a lot of patience and determination. But,
+don't give up. It's possible. Many have done it before, and each had to
+start exactly where you are now.
+
+
 
 
 
 ----------
 Thanks to Randy Dunlap and Gerrit Huizenga for the list of things you
-should and should not say.  Also to XXX for their review and comments on
-early drafts of this document.
+should and should not say.  Also to Pat Mochel for their review and
+comments on early drafts of this document.