diff options
Diffstat (limited to 'Documentation')
58 files changed, 2721 insertions, 584 deletions
diff --git a/Documentation/Changes b/Documentation/Changes index 86b86399d61d..fe5ae0f55020 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -31,8 +31,6 @@ al espaņol de este documento en varios formatos. Eine deutsche Version dieser Datei finden Sie unter <http://www.stefan-winter.de/Changes-2.4.0.txt>. -Last updated: October 29th, 2002 - Chris Ricker (kaboom@gatech.edu or chris.ricker@genetics.utah.edu). Current Minimal Requirements @@ -48,7 +46,7 @@ necessary on all systems; obviously, if you don't have any ISDN hardware, for example, you probably needn't concern yourself with isdn4k-utils. -o Gnu C 2.95.3 # gcc --version +o Gnu C 3.2 # gcc --version o Gnu make 3.79.1 # make --version o binutils 2.12 # ld -v o util-linux 2.10o # fdformat --version @@ -74,26 +72,7 @@ GCC --- The gcc version requirements may vary depending on the type of CPU in your -computer. The next paragraph applies to users of x86 CPUs, but not -necessarily to users of other CPUs. Users of other CPUs should obtain -information about their gcc version requirements from another source. - -The recommended compiler for the kernel is gcc 2.95.x (x >= 3), and it -should be used when you need absolute stability. You may use gcc 3.0.x -instead if you wish, although it may cause problems. Later versions of gcc -have not received much testing for Linux kernel compilation, and there are -almost certainly bugs (mainly, but not exclusively, in the kernel) that -will need to be fixed in order to use these compilers. In any case, using -pgcc instead of plain gcc is just asking for trouble. - -The Red Hat gcc 2.96 compiler subtree can also be used to build this tree. -You should ensure you use gcc-2.96-74 or later. gcc-2.96-54 will not build -the kernel correctly. - -In addition, please pay attention to compiler optimization. Anything -greater than -O2 may not be wise. Similarly, if you choose to use gcc-2.95.x -or derivatives, be sure not to use -fstrict-aliasing (which, depending on -your version of gcc 2.95.x, may necessitate using -fno-strict-aliasing). +computer. Make ---- @@ -322,9 +301,9 @@ Getting updated software Kernel compilation ****************** -gcc 2.95.3 ----------- -o <ftp://ftp.gnu.org/gnu/gcc/gcc-2.95.3.tar.gz> +gcc +--- +o <ftp://ftp.gnu.org/gnu/gcc/> Make ---- diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index eb7db3c19227..ce5d2c038cf5 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -199,7 +199,7 @@ The rationale is: modifications are prevented - saves the compiler work to optimize redundant code away ;) -int fun(int ) +int fun(int a) { int result = 0; char *buffer = kmalloc(SIZE); @@ -344,7 +344,7 @@ Remember: if another thread can find your data structure, and you don't have a reference count on it, you almost certainly have a bug. - Chapter 11: Macros, Enums, Inline functions and RTL + Chapter 11: Macros, Enums and RTL Names of macros defining constants and labels in enums are capitalized. @@ -429,7 +429,35 @@ from void pointer to any other pointer type is guaranteed by the C programming language. - Chapter 14: References + Chapter 14: The inline disease + +There appears to be a common misperception that gcc has a magic "make me +faster" speedup option called "inline". While the use of inlines can be +appropriate (for example as a means of replacing macros, see Chapter 11), it +very often is not. Abundant use of the inline keyword leads to a much bigger +kernel, which in turn slows the system as a whole down, due to a bigger +icache footprint for the CPU and simply because there is less memory +available for the pagecache. Just think about it; a pagecache miss causes a +disk seek, which easily takes 5 miliseconds. There are a LOT of cpu cycles +that can go into these 5 miliseconds. + +A reasonable rule of thumb is to not put inline at functions that have more +than 3 lines of code in them. An exception to this rule are the cases where +a parameter is known to be a compiletime constant, and as a result of this +constantness you *know* the compiler will be able to optimize most of your +function away at compile time. For a good example of this later case, see +the kmalloc() inline function. + +Often people argue that adding inline to functions that are static and used +only once is always a win since there is no space tradeoff. While this is +technically correct, gcc is capable of inlining these automatically without +help, and the maintenance issue of removing the inline when a second user +appears outweighs the potential value of the hint that tells gcc to do +something it would have done anyway. + + + + Chapter 15: References The C Programming Language, Second Edition by Brian W. Kernighan and Dennis M. Ritchie. @@ -444,10 +472,13 @@ ISBN 0-201-61586-X. URL: http://cm.bell-labs.com/cm/cs/tpop/ GNU manuals - where in compliance with K&R and this text - for cpp, gcc, -gcc internals and indent, all available from http://www.gnu.org +gcc internals and indent, all available from http://www.gnu.org/manual/ WG14 is the international standardization working group for the programming -language C, URL: http://std.dkuug.dk/JTC1/SC22/WG14/ +language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ + +Kernel CodingStyle, by greg@kroah.com at OLS 2002: +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ -- -Last updated on 16 February 2004 by a community effort on LKML. +Last updated on 30 December 2005 by a community effort on LKML. diff --git a/Documentation/DocBook/.gitignore b/Documentation/DocBook/.gitignore new file mode 100644 index 000000000000..c102c02ecf89 --- /dev/null +++ b/Documentation/DocBook/.gitignore @@ -0,0 +1,6 @@ +*.xml +*.ps +*.pdf +*.html +*.9.gz +*.9 diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 767433bdbc40..8c9c6704e85b 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -54,6 +54,11 @@ !Ekernel/sched.c !Ekernel/timer.c </sect1> + <sect1><title>High-resolution timers</title> +!Iinclude/linux/ktime.h +!Iinclude/linux/hrtimer.h +!Ekernel/hrtimer.c + </sect1> <sect1><title>Internal Functions</title> !Ikernel/exit.c !Ikernel/signal.c @@ -369,6 +374,7 @@ X!Edrivers/acpi/motherboard.c X!Edrivers/acpi/bus.c --> !Edrivers/acpi/scan.c +!Idrivers/acpi/scan.c <!-- No correct structured comments X!Edrivers/acpi/pci_bind.c --> diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl index 90dc2de8e0af..158ffe9bfade 100644 --- a/Documentation/DocBook/kernel-locking.tmpl +++ b/Documentation/DocBook/kernel-locking.tmpl @@ -222,7 +222,7 @@ <title>Two Main Types of Kernel Locks: Spinlocks and Semaphores</title> <para> - There are two main types of kernel locks. The fundamental type + There are three main types of kernel locks. The fundamental type is the spinlock (<filename class="headerfile">include/asm/spinlock.h</filename>), which is a very simple single-holder lock: if you can't get the @@ -230,16 +230,22 @@ very small and fast, and can be used anywhere. </para> <para> - The second type is a semaphore + The second type is a mutex + (<filename class="headerfile">include/linux/mutex.h</filename>): it + is like a spinlock, but you may block holding a mutex. + If you can't lock a mutex, your task will suspend itself, and be woken + up when the mutex is released. This means the CPU can do something + else while you are waiting. There are many cases when you simply + can't sleep (see <xref linkend="sleeping-things"/>), and so have to + use a spinlock instead. + </para> + <para> + The third type is a semaphore (<filename class="headerfile">include/asm/semaphore.h</filename>): it can have more than one holder at any time (the number decided at initialization time), although it is most commonly used as a - single-holder lock (a mutex). If you can't get a semaphore, - your task will put itself on the queue, and be woken up when the - semaphore is released. This means the CPU will do something - else while you are waiting, but there are many cases when you - simply can't sleep (see <xref linkend="sleeping-things"/>), and so - have to use a spinlock instead. + single-holder lock (a mutex). If you can't get a semaphore, your + task will be suspended and later on woken up - just like for mutexes. </para> <para> Neither type of lock is recursive: see diff --git a/Documentation/RCU/rcuref.txt b/Documentation/RCU/rcuref.txt index a23fee66064d..3f60db41b2f0 100644 --- a/Documentation/RCU/rcuref.txt +++ b/Documentation/RCU/rcuref.txt @@ -1,74 +1,67 @@ -Refcounter framework for elements of lists/arrays protected by -RCU. +Refcounter design for elements of lists/arrays protected by RCU. Refcounting on elements of lists which are protected by traditional reader/writer spinlocks or semaphores are straight forward as in: -1. 2. -add() search_and_reference() -{ { - alloc_object read_lock(&list_lock); - ... search_for_element - atomic_set(&el->rc, 1); atomic_inc(&el->rc); - write_lock(&list_lock); ... - add_element read_unlock(&list_lock); - ... ... - write_unlock(&list_lock); } +1. 2. +add() search_and_reference() +{ { + alloc_object read_lock(&list_lock); + ... search_for_element + atomic_set(&el->rc, 1); atomic_inc(&el->rc); + write_lock(&list_lock); ... + add_element read_unlock(&list_lock); + ... ... + write_unlock(&list_lock); } } 3. 4. release_referenced() delete() { { - ... write_lock(&list_lock); - atomic_dec(&el->rc, relfunc) ... - ... delete_element -} write_unlock(&list_lock); - ... - if (atomic_dec_and_test(&el->rc)) - kfree(el); - ... + ... write_lock(&list_lock); + atomic_dec(&el->rc, relfunc) ... + ... delete_element +} write_unlock(&list_lock); + ... + if (atomic_dec_and_test(&el->rc)) + kfree(el); + ... } If this list/array is made lock free using rcu as in changing the write_lock in add() and delete() to spin_lock and changing read_lock -in search_and_reference to rcu_read_lock(), the rcuref_get in +in search_and_reference to rcu_read_lock(), the atomic_get in search_and_reference could potentially hold reference to an element which -has already been deleted from the list/array. rcuref_lf_get_rcu takes +has already been deleted from the list/array. atomic_inc_not_zero takes care of this scenario. search_and_reference should look as; 1. 2. add() search_and_reference() { { - alloc_object rcu_read_lock(); - ... search_for_element - atomic_set(&el->rc, 1); if (rcuref_inc_lf(&el->rc)) { - write_lock(&list_lock); rcu_read_unlock(); - return FAIL; - add_element } - ... ... - write_unlock(&list_lock); rcu_read_unlock(); + alloc_object rcu_read_lock(); + ... search_for_element + atomic_set(&el->rc, 1); if (atomic_inc_not_zero(&el->rc)) { + write_lock(&list_lock); rcu_read_unlock(); + return FAIL; + add_element } + ... ... + write_unlock(&list_lock); rcu_read_unlock(); } } 3. 4. release_referenced() delete() { { - ... write_lock(&list_lock); - rcuref_dec(&el->rc, relfunc) ... - ... delete_element -} write_unlock(&list_lock); - ... - if (rcuref_dec_and_test(&el->rc)) - call_rcu(&el->head, el_free); - ... + ... write_lock(&list_lock); + atomic_dec(&el->rc, relfunc) ... + ... delete_element +} write_unlock(&list_lock); + ... + if (atomic_dec_and_test(&el->rc)) + call_rcu(&el->head, el_free); + ... } Sometimes, reference to the element need to be obtained in the -update (write) stream. In such cases, rcuref_inc_lf might be an overkill -since the spinlock serialising list updates are held. rcuref_inc +update (write) stream. In such cases, atomic_inc_not_zero might be an +overkill since the spinlock serialising list updates are held. atomic_inc is to be used in such cases. -For arches which do not have cmpxchg rcuref_inc_lf -api uses a hashed spinlock implementation and the same hashed spinlock -is acquired in all rcuref_xxx primitives to preserve atomicity. -Note: Use rcuref_inc api only if you need to use rcuref_inc_lf on the -refcounter atleast at one place. Mixing rcuref_inc and atomic_xxx api -might lead to races. rcuref_inc_lf() must be used in lockfree -RCU critical sections only. + diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index c3cca924e94b..dd311cff1cc3 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -27,18 +27,17 @@ Who To Submit Drivers To ------------------------ Linux 2.0: - No new drivers are accepted for this kernel tree + No new drivers are accepted for this kernel tree. Linux 2.2: + No new drivers are accepted for this kernel tree. + +Linux 2.4: If the code area has a general maintainer then please submit it to the maintainer listed in MAINTAINERS in the kernel file. If the maintainer does not respond or you cannot find the appropriate - maintainer then please contact the 2.2 kernel maintainer: - Marc-Christian Petersen <m.c.p@wolk-project.de>. - -Linux 2.4: - The same rules apply as 2.2. The final contact point for Linux 2.4 - submissions is Marcelo Tosatti <marcelo.tosatti@cyclades.com>. + maintainer then please contact Marcelo Tosatti + <marcelo.tosatti@cyclades.com>. Linux 2.6: The same rules apply as 2.4 except that you should follow linux-kernel @@ -53,6 +52,7 @@ Licensing: The code must be released to us under the of exclusive GPL licensing, and if you wish the driver to be useful to other communities such as BSD you may well wish to release under multiple licenses. + See accepted licenses at include/linux/module.h Copyright: The copyright owner must agree to use of GPL. It's best if the submitter and copyright owner @@ -143,5 +143,13 @@ KernelNewbies: http://kernelnewbies.org/ Linux USB project: - http://sourceforge.net/projects/linux-usb/ + http://linux-usb.sourceforge.net/ + +How to NOT write kernel driver by arjanv@redhat.com + http://people.redhat.com/arjanv/olspaper.pdf + +Kernel Janitor: + http://janitor.kernelnewbies.org/ +-- +Last updated on 17 Nov 2005. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 1d47e6c09dc6..6198e5ebcf65 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -78,7 +78,9 @@ Randy Dunlap's patch scripts: http://www.xenotime.net/linux/scripts/patching-scripts-002.tar.gz Andrew Morton's patch scripts: -http://www.zip.com.au/~akpm/linux/patches/patch-scripts-0.20 +http://www.zip.com.au/~akpm/linux/patches/ +Instead of these scripts, quilt is the recommended patch management +tool (see above). @@ -97,7 +99,7 @@ need to split up your patch. See #3, next. 3) Separate your changes. -Separate each logical change into its own patch. +Separate _logical changes_ into a single patch file. For example, if your changes include both bug fixes and performance enhancements for a single driver, separate those changes into two @@ -112,6 +114,10 @@ If one patch depends on another patch in order for a change to be complete, that is OK. Simply note "this patch depends on patch X" in your patch description. +If you cannot condense your patch set into a smaller set of patches, +then only post say 15 or so at a time and wait for review and integration. + + 4) Select e-mail destination. @@ -124,6 +130,10 @@ your patch to the primary Linux kernel developer's mailing list, linux-kernel@vger.kernel.org. Most kernel developers monitor this e-mail list, and can comment on your changes. + +Do not send more than 15 patches at once to the vger mailing lists!!! + + Linus Torvalds is the final arbiter of all changes accepted into the Linux kernel. His e-mail address is <torvalds@osdl.org>. He gets a lot of e-mail, so typically you should do your best to -avoid- sending @@ -149,6 +159,9 @@ USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the MAINTAINERS file for a mailing list that relates specifically to your change. +Majordomo lists of VGER.KERNEL.ORG at: + <http://vger.kernel.org/vger-lists.html> + If changes affect userland-kernel interfaces, please send the MAN-PAGES maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at least a notification of the change, @@ -373,27 +386,14 @@ a diffstat, to show what files have changed, and the number of inserted and deleted lines per file. A diffstat is especially useful on bigger patches. Other comments relevant only to the moment or the maintainer, not suitable for the permanent changelog, should also go here. +Use diffstat options "-p 1 -w 70" so that filenames are listed from the +top of the kernel source tree and don't use too much horizontal space +(easily fit in 80 columns, maybe with some indentation). See more details on the proper patch format in the following references. -13) More references for submitting patches - -Andrew Morton, "The perfect patch" (tpp). - <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt> - -Jeff Garzik, "Linux kernel patch submission format." - <http://linux.yyz.us/patch-format.html> - -Greg KH, "How to piss off a kernel subsystem maintainer" - <http://www.kroah.com/log/2005/03/31/> - -Kernel Documentation/CodingStyle - <http://sosdg.org/~coywolf/lxr/source/Documentation/CodingStyle> - -Linus Torvald's mail on the canonical patch format: - <http://lkml.org/lkml/2005/4/7/183> ----------------------------------- @@ -466,3 +466,30 @@ and 'extern __inline__'. Don't try to anticipate nebulous future cases which may or may not be useful: "Make it as simple as you can, and no simpler." + + +---------------------- +SECTION 3 - REFERENCES +---------------------- + +Andrew Morton, "The perfect patch" (tpp). + <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt> + +Jeff Garzik, "Linux kernel patch submission format." + <http://linux.yyz.us/patch-format.html> + +Greg Kroah, "How to piss off a kernel subsystem maintainer". + <http://www.kroah.com/log/2005/03/31/> + <http://www.kroah.com/log/2005/07/08/> + <http://www.kroah.com/log/2005/10/19/> + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!. + <http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2> + +Kernel Documentation/CodingStyle + <http://sosdg.org/~coywolf/lxr/source/Documentation/CodingStyle> + +Linus Torvald's mail on the canonical patch format: + <http://lkml.org/lkml/2005/4/7/183> +-- +Last updated on 17 Nov 2005. diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index 681e426e2482..a083ba35d1ad 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -2,8 +2,8 @@ Applying Patches To The Linux Kernel ------------------------------------ - (Written by Jesper Juhl, August 2005) - + Original by: Jesper Juhl, August 2005 + Last update: 2006-01-05 A frequently asked question on the Linux Kernel Mailing List is how to apply @@ -76,7 +76,7 @@ instead: If you |