diff options
Diffstat (limited to 'Documentation')
55 files changed, 977 insertions, 253 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/DocBook/Makefile b/Documentation/DocBook/Makefile index 7018f5c6a44..1c955883cf5 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -20,6 +20,12 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ # +--> DIR=file (htmldocs) # +--> man/ (mandocs) + +# for PDF and PS output you can choose between xmlto and docbook-utils tools +PDF_METHOD = $(prefer-db2x) +PS_METHOD = $(prefer-db2x) + + ### # The targets that may be used. .PHONY: xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs @@ -93,27 +99,39 @@ C-procfs-example = procfs_example.xml C-procfs-example2 = $(addprefix $(obj)/,$(C-procfs-example)) $(obj)/procfs-guide.xml: $(C-procfs-example2) -### -# Rules to generate postscript, PDF and HTML -# db2html creates a directory. Generate a html file used for timestamp +notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \ + exit 1 +db2xtemplate = db2TYPE -o $(dir $@) $< +xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $< + +# determine which methods are available +ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found) + use-db2x = db2x + prefer-db2x = db2x +else + use-db2x = notfound + prefer-db2x = $(use-xmlto) +endif +ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found) + use-xmlto = xmlto + prefer-xmlto = xmlto +else + use-xmlto = notfound + prefer-xmlto = $(use-db2x) +endif -quiet_cmd_db2ps = XMLTO $@ - cmd_db2ps = xmlto ps $(XMLTOFLAGS) -o $(dir $@) $< +# the commands, generated from the chosen template +quiet_cmd_db2ps = PS $@ + cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template)) %.ps : %.xml - @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install xmlto ***"; \ - exit 1) $(call cmd,db2ps) -quiet_cmd_db2pdf = XMLTO $@ - cmd_db2pdf = xmlto pdf $(XMLTOFLAGS) -o $(dir $@) $< +quiet_cmd_db2pdf = PDF $@ + cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template)) %.pdf : %.xml - @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install xmlto ***"; \ - exit 1) $(call cmd,db2pdf) -quiet_cmd_db2html = XMLTO $@ +quiet_cmd_db2html = HTML $@ cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ @@ -127,7 +145,7 @@ quiet_cmd_db2html = XMLTO $@ @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \ cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi -quiet_cmd_db2man = XMLTO $@ +quiet_cmd_db2man = MAN $@ cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi %.9 : %.xml @(which xmlto > /dev/null 2>&1) || \ diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index a8316b1a3e3..767433bdbc4 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -68,9 +68,7 @@ X!Iinclude/linux/kobject.h <sect1><title>Kernel utility functions</title> !Iinclude/linux/kernel.h -<!-- This needs to clean up to make kernel-doc happy -X!Ekernel/printk.c - --> +!Ekernel/printk.c !Ekernel/panic.c !Ekernel/sys.c !Ekernel/rcupdate.c @@ -239,8 +237,10 @@ X!Ilib/string.c <sect1><title>Driver Support</title> !Enet/core/dev.c !Enet/ethernet/eth.c -!Einclude/linux/etherdevice.h -!Enet/core/wireless.c +!Iinclude/linux/etherdevice.h +<!-- FIXME: Removed for now since no structured comments in source +X!Enet/core/wireless.c +--> </sect1> <sect1><title>Synchronous PPP</title> !Edrivers/net/wan/syncppp.c @@ -388,7 +388,7 @@ X!Edrivers/pnp/system.c <chapter id="blkdev"> <title>Block Devices</title> -!Edrivers/block/ll_rw_blk.c +!Eblock/ll_rw_blk.c </chapter> <chapter id="miscdev"> diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl index 64be9f7ee3b..3ccce886c34 100644 --- a/Documentation/DocBook/stylesheet.xsl +++ b/Documentation/DocBook/stylesheet.xsl @@ -3,4 +3,5 @@ <param name="chunk.quietly">1</param> <param name="funcsynopsis.style">ansi</param> <param name="funcsynopsis.tabular.threshold">80</param> +<!-- <param name="paper.type">A4</param> --> </stylesheet> 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 development tree, Dave Airlie <airlied@linux.ie> + kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git + + - ia64 development tree, Tony Luck <tony.luck@intel.com> + kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git + + - ieee1394 development tree, Jody McIntyre <scjody@modernduck.com> + kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git + + - infiniband, Roland Dreier <rolandd@cisco.com> + kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git + + - libata, Jeff Garzik <jgarzik@pobox.com> + kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git + + - network drivers, Jeff Garzik <jgarzik@pobox.com> + kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git + + - pcmcia, Dominik Brodowski <linux@dominikbrodowski.net> + kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git + + - SCSI, James Bottomley <James.Bottomley@SteelEye.com> + kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git + + Other git kernel trees can be found listed at http://kernel.org/git + + quilt trees: + - USB, PCI, Driver Core, and I2C, Greg Kroah-Hartman <gregkh@suse.de> + kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/ + + +Bug Reporting +------------- + +bugzilla.kernel.org is where the Linux kernel developers track kernel +bugs. Users are encouraged to report all bugs that they find in this +tool. For details on how to use the kernel bugzilla, please see: + http://test.kernel.org/bugzilla/faq.html + +The file REPORTING-BUGS in the main kernel source directory has a good +template for how to report a possible kernel bug, and details what kind +of information is needed by the kernel developers to help track down the +problem. + + +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: + http://vger.kernel.org/vger-lists.html#linux-kernel +There are archives of the mailing list on the web in many different +places. Use a search engine to find these archives. For example: + http://dir.gmane.org/gmane.linux.kernel +It is highly recommended that you search the archives about the topic +you want to bring up, before you post it to the list. A lot of things +already discussed in detail are only recorded at the mailing list +archives. + +Most of the individual kernel subsystems also have their own separate +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 at: + http://vger.kernel.org/vger-lists.html + |