Commit 93567c43 authored by Linus Torvalds's avatar Linus Torvalds

Merge branch 'docs-next' of git://git.lwn.net/linux-2.6

* 'docs-next' of git://git.lwn.net/linux-2.6:
  docs: update the development process document
  docs: fix dev_debug() braino in dynamic-debug-howto.txt
parents 1680a013 5c050fb9
...@@ -56,13 +56,13 @@ information on kernel development. ...@@ -56,13 +56,13 @@ information on kernel development.
1.2: WHAT THIS DOCUMENT IS ABOUT 1.2: WHAT THIS DOCUMENT IS ABOUT
The Linux kernel, at over 6 million lines of code and well over 1000 active The Linux kernel, at over 8 million lines of code and well over 1000
contributors, is one of the largest and most active free software projects contributors to each release, is one of the largest and most active free
in existence. Since its humble beginning in 1991, this kernel has evolved software projects in existence. Since its humble beginning in 1991, this
into a best-of-breed operating system component which runs on pocket-sized kernel has evolved into a best-of-breed operating system component which
digital music players, desktop PCs, the largest supercomputers in runs on pocket-sized digital music players, desktop PCs, the largest
existence, and all types of systems in between. It is a robust, efficient, supercomputers in existence, and all types of systems in between. It is a
and scalable solution for almost any situation. robust, efficient, and scalable solution for almost any situation.
With the growth of Linux has come an increase in the number of developers With the growth of Linux has come an increase in the number of developers
(and companies) wishing to participate in its development. Hardware (and companies) wishing to participate in its development. Hardware
...@@ -115,7 +115,7 @@ This document was written by Jonathan Corbet, corbet@lwn.net. It has been ...@@ -115,7 +115,7 @@ This document was written by Jonathan Corbet, corbet@lwn.net. It has been
improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh,
Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and
Jochen Voß. Jochen Voß.
This work was supported by the Linux Foundation; thanks especially to This work was supported by the Linux Foundation; thanks especially to
Amanda McPherson, who saw the value of this effort and made it all happen. Amanda McPherson, who saw the value of this effort and made it all happen.
...@@ -221,7 +221,7 @@ include: ...@@ -221,7 +221,7 @@ include:
- Everything that was said above about code review applies doubly to - Everything that was said above about code review applies doubly to
closed-source code. Since this code is not available at all, it cannot closed-source code. Since this code is not available at all, it cannot
have been reviewed by the community and will, beyond doubt, have serious have been reviewed by the community and will, beyond doubt, have serious
problems. problems.
Makers of embedded systems, in particular, may be tempted to disregard much Makers of embedded systems, in particular, may be tempted to disregard much
of what has been said in this section in the belief that they are shipping of what has been said in this section in the belief that they are shipping
......
This diff is collapsed.
...@@ -110,8 +110,8 @@ the kernel community's standards. Some examples include: ...@@ -110,8 +110,8 @@ the kernel community's standards. Some examples include:
- The AppArmor security module made use of internal virtual filesystem - The AppArmor security module made use of internal virtual filesystem
data structures in ways which were considered to be unsafe and data structures in ways which were considered to be unsafe and
unreliable. This code has since been significantly reworked, but unreliable. This concern (among others) kept AppArmor out of the
remains outside of the mainline. mainline for years.
In each of these cases, a great deal of pain and extra work could have been In each of these cases, a great deal of pain and extra work could have been
avoided with some early discussion with the kernel developers. avoided with some early discussion with the kernel developers.
...@@ -138,6 +138,19 @@ patches, and who, if anybody, is attaching Signed-off-by lines to those ...@@ -138,6 +138,19 @@ patches, and who, if anybody, is attaching Signed-off-by lines to those
patches. Those are the people who will be best placed to help with a new patches. Those are the people who will be best placed to help with a new
development project. development project.
The task of finding the right maintainer is sometimes challenging enough
that the kernel developers have added a script to ease the process:
.../scripts/get_maintainer.pl
This script will return the current maintainer(s) for a given file or
directory when given the "-f" option. If passed a patch on the
command line, it will list the maintainers who should probably receive
copies of the patch. There are a number of options regulating how hard
get_maintainer.pl will search for maintainers; please be careful about
using the more aggressive options as you may end up including developers
who have no real interest in the code you are modifying.
If all else fails, talking to Andrew Morton can be an effective way to If all else fails, talking to Andrew Morton can be an effective way to
track down a maintainer for a specific piece of code. track down a maintainer for a specific piece of code.
...@@ -155,11 +168,15 @@ reaction, but, instead, little or no reaction at all. The sad truth of the ...@@ -155,11 +168,15 @@ reaction, but, instead, little or no reaction at all. The sad truth of the
matter is (1) kernel developers tend to be busy, (2) there is no shortage matter is (1) kernel developers tend to be busy, (2) there is no shortage
of people with grand plans and little code (or even prospect of code) to of people with grand plans and little code (or even prospect of code) to
back them up, and (3) nobody is obligated to review or comment on ideas back them up, and (3) nobody is obligated to review or comment on ideas
posted by others. If a request-for-comments posting yields little in the posted by others. Beyond that, high-level designs often hide problems
way of comments, do not assume that it means there is no interest in the which are only reviewed when somebody actually tries to implement those
project. Unfortunately, you also cannot assume that there are no problems designs; for that reason, kernel developers would rather see the code.
with your idea. The best thing to do in this situation is to proceed,
keeping the community informed as you go. If a request-for-comments posting yields little in the way of comments, do
not assume that it means there is no interest in the project.
Unfortunately, you also cannot assume that there are no problems with your
idea. The best thing to do in this situation is to proceed, keeping the
community informed as you go.
3.5: GETTING OFFICIAL BUY-IN 3.5: GETTING OFFICIAL BUY-IN
......
...@@ -131,6 +131,11 @@ classic time/space tradeoff taught in beginning data structures classes ...@@ -131,6 +131,11 @@ classic time/space tradeoff taught in beginning data structures classes
often does not apply to contemporary hardware. Space *is* time, in that a often does not apply to contemporary hardware. Space *is* time, in that a
larger program will run slower than one which is more compact. larger program will run slower than one which is more compact.
More recent compilers take an increasingly active role in deciding whether
a given function should actually be inlined or not. So the liberal
placement of "inline" keywords may not just be excessive; it could also be
irrelevant.
* Locking * Locking
...@@ -285,6 +290,13 @@ be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your ...@@ -285,6 +290,13 @@ be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your
distributor does not package it); it can then be run on the code by adding distributor does not package it); it can then be run on the code by adding
"C=1" to your make command. "C=1" to your make command.
The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide
variety of potential coding problems; it can also propose fixes for those
problems. Quite a few "semantic patches" for the kernel have been packaged
under the scripts/coccinelle directory; running "make coccicheck" will run
through those semantic patches and report on any problems found. See
Documentation/coccinelle.txt for more information.
Other kinds of portability errors are best found by compiling your code for Other kinds of portability errors are best found by compiling your code for
other architectures. If you do not happen to have an S/390 system or a other architectures. If you do not happen to have an S/390 system or a
Blackfin development board handy, you can still perform the compilation Blackfin development board handy, you can still perform the compilation
...@@ -308,7 +320,9 @@ The first piece of documentation for any patch is its associated ...@@ -308,7 +320,9 @@ The first piece of documentation for any patch is its associated
changelog. Log entries should describe the problem being solved, the form changelog. Log entries should describe the problem being solved, the form
of the solution, the people who worked on the patch, any relevant of the solution, the people who worked on the patch, any relevant
effects on performance, and anything else that might be needed to effects on performance, and anything else that might be needed to
understand the patch. understand the patch. Be sure that the changelog says *why* the patch is
worth applying; a surprising number of developers fail to provide that
information.
Any code which adds a new user-space interface - including new sysfs or Any code which adds a new user-space interface - including new sysfs or
/proc files - should include documentation of that interface which enables /proc files - should include documentation of that interface which enables
...@@ -321,7 +335,7 @@ boot-time parameters. Any patch which adds new parameters should add the ...@@ -321,7 +335,7 @@ boot-time parameters. Any patch which adds new parameters should add the
appropriate entries to this file. appropriate entries to this file.
Any new configuration options must be accompanied by help text which Any new configuration options must be accompanied by help text which
clearly explains the options and when the user might want to select them. clearly explains the options and when the user might want to select them.
Internal API information for many subsystems is documented by way of Internal API information for many subsystems is documented by way of
specially-formatted comments; these comments can be extracted and formatted specially-formatted comments; these comments can be extracted and formatted
...@@ -372,7 +386,8 @@ which is broken by the change. For a widely-used function, this duty can ...@@ -372,7 +386,8 @@ which is broken by the change. For a widely-used function, this duty can
lead to literally hundreds or thousands of changes - many of which are lead to literally hundreds or thousands of changes - many of which are
likely to conflict with work being done by other developers. Needless to likely to conflict with work being done by other developers. Needless to
say, this can be a large job, so it is best to be sure that the say, this can be a large job, so it is best to be sure that the
justification is solid. justification is solid. Note that the Coccinelle tool can help with
wide-ranging API changes.
When making an incompatible API change, one should, whenever possible, When making an incompatible API change, one should, whenever possible,
ensure that code which has not been updated is caught by the compiler. ensure that code which has not been updated is caught by the compiler.
......
...@@ -60,12 +60,15 @@ even in the short term. ...@@ -60,12 +60,15 @@ even in the short term.
Patches must be prepared against a specific version of the kernel. As a Patches must be prepared against a specific version of the kernel. As a
general rule, a patch should be based on the current mainline as found in general rule, a patch should be based on the current mainline as found in
Linus's git tree. It may become necessary to make versions against -mm, Linus's git tree. When basing on mainline, start with a well-known release
linux-next, or a subsystem tree, though, to facilitate wider testing and point - a stable or -rc release - rather than branching off the mainline at
review. Depending on the area of your patch and what is going on an arbitrary spot.
elsewhere, basing a patch against these other trees can require a
significant amount of work resolving conflicts and dealing with API It may become necessary to make versions against -mm, linux-next, or a
changes. subsystem tree, though, to facilitate wider testing and review. Depending
on the area of your patch and what is going on elsewhere, basing a patch
against these other trees can require a significant amount of work
resolving conflicts and dealing with API changes.
Only the most simple changes should be formatted as a single patch; Only the most simple changes should be formatted as a single patch;
everything else should be made as a logical series of changes. Splitting everything else should be made as a logical series of changes. Splitting
...@@ -100,11 +103,11 @@ rules of thumb, however, which can help considerably: ...@@ -100,11 +103,11 @@ rules of thumb, however, which can help considerably:
result is a broken kernel, you will make life harder for developers and result is a broken kernel, you will make life harder for developers and
users who are engaging in the noble work of tracking down problems. users who are engaging in the noble work of tracking down problems.
- Do not overdo it, though. One developer recently posted a set of edits - Do not overdo it, though. One developer once posted a set of edits
to a single file as 500 separate patches - an act which did not make him to a single file as 500 separate patches - an act which did not make him
the most popular person on the kernel mailing list. A single patch can the most popular person on the kernel mailing list. A single patch can
be reasonably large as long as it still contains a single *logical* be reasonably large as long as it still contains a single *logical*
change. change.
- It can be tempting to add a whole new infrastructure with a series of - It can be tempting to add a whole new infrastructure with a series of
patches, but to leave that infrastructure unused until the final patch patches, but to leave that infrastructure unused until the final patch
...@@ -162,7 +165,8 @@ To that end, the summary line should describe the effects of and motivation ...@@ -162,7 +165,8 @@ To that end, the summary line should describe the effects of and motivation
for the change as well as possible given the one-line constraint. The for the change as well as possible given the one-line constraint. The
detailed description can then amplify on those topics and provide any detailed description can then amplify on those topics and provide any
needed additional information. If the patch fixes a bug, cite the commit needed additional information. If the patch fixes a bug, cite the commit
which introduced the bug if possible. If a problem is associated with which introduced the bug if possible (and please provide both the commit ID
and the title when citing commits). If a problem is associated with
specific log or compiler output, include that output to help others specific log or compiler output, include that output to help others
searching for a solution to the same problem. If the change is meant to searching for a solution to the same problem. If the change is meant to
support other changes coming in later patch, say so. If internal APIs are support other changes coming in later patch, say so. If internal APIs are
...@@ -230,7 +234,7 @@ take care of: ...@@ -230,7 +234,7 @@ take care of:
which have had gratuitous white-space changes or line wrapping performed which have had gratuitous white-space changes or line wrapping performed
by the mail client will not apply at the other end, and often will not by the mail client will not apply at the other end, and often will not
be examined in any detail. If there is any doubt at all, mail the patch be examined in any detail. If there is any doubt at all, mail the patch
to yourself and convince yourself that it shows up intact. to yourself and convince yourself that it shows up intact.
Documentation/email-clients.txt has some helpful hints on making Documentation/email-clients.txt has some helpful hints on making
specific mail clients work for sending patches. specific mail clients work for sending patches.
...@@ -287,7 +291,7 @@ something like: ...@@ -287,7 +291,7 @@ something like:
where "nn" is the ordinal number of the patch, "mm" is the total number of where "nn" is the ordinal number of the patch, "mm" is the total number of
patches in the series, and "subsys" is the name of the affected subsystem. patches in the series, and "subsys" is the name of the affected subsystem.
Clearly, nn/mm can be omitted for a single, standalone patch. Clearly, nn/mm can be omitted for a single, standalone patch.
If you have a significant series of patches, it is customary to send an If you have a significant series of patches, it is customary to send an
introductory description as part zero. This convention is not universally introductory description as part zero. This convention is not universally
...@@ -299,5 +303,5 @@ In general, the second and following parts of a multi-part patch should be ...@@ -299,5 +303,5 @@ In general, the second and following parts of a multi-part patch should be
sent as a reply to the first part so that they all thread together at the sent as a reply to the first part so that they all thread together at the
receiving end. Tools like git and quilt have commands to mail out a set of receiving end. Tools like git and quilt have commands to mail out a set of
patches with the proper threading. If you have a long series, though, and patches with the proper threading. If you have a long series, though, and
are using git, please provide the --no-chain-reply-to option to avoid are using git, please stay away from the --chain-reply-to option to avoid
creating exceptionally deep nesting. creating exceptionally deep nesting.
...@@ -66,6 +66,11 @@ be easy to become blinded by your own solution to a problem to the point ...@@ -66,6 +66,11 @@ be easy to become blinded by your own solution to a problem to the point
that you don't realize that something is fundamentally wrong or, perhaps, that you don't realize that something is fundamentally wrong or, perhaps,
you're not even solving the right problem. you're not even solving the right problem.
Andrew Morton has suggested that every review comment which does not result
in a code change should result in an additional code comment instead; that
can help future reviewers avoid the questions which came up the first time
around.
One fatal mistake is to ignore review comments in the hope that they will One fatal mistake is to ignore review comments in the hope that they will
go away. They will not go away. If you repost code without having go away. They will not go away. If you repost code without having
responded to the comments you got the time before, you're likely to find responded to the comments you got the time before, you're likely to find
...@@ -100,7 +105,7 @@ entry into a subsystem maintainer's tree. How that works varies from one ...@@ -100,7 +105,7 @@ entry into a subsystem maintainer's tree. How that works varies from one
subsystem to the next; each maintainer has his or her own way of doing subsystem to the next; each maintainer has his or her own way of doing
things. In particular, there may be more than one tree - one, perhaps, things. In particular, there may be more than one tree - one, perhaps,
dedicated to patches planned for the next merge window, and another for dedicated to patches planned for the next merge window, and another for
longer-term work. longer-term work.
For patches applying to areas for which there is no obvious subsystem tree For patches applying to areas for which there is no obvious subsystem tree
(memory management patches, for example), the default tree often ends up (memory management patches, for example), the default tree often ends up
...@@ -109,11 +114,10 @@ through the -mm tree. ...@@ -109,11 +114,10 @@ through the -mm tree.
Inclusion into a subsystem tree can bring a higher level of visibility to a Inclusion into a subsystem tree can bring a higher level of visibility to a
patch. Now other developers working with that tree will get the patch by patch. Now other developers working with that tree will get the patch by
default. Subsystem trees typically feed into -mm and linux-next as well, default. Subsystem trees typically feed linux-next as well, making their
making their contents visible to the development community as a whole. At contents visible to the development community as a whole. At this point,
this point, there's a good chance that you will get more comments from a there's a good chance that you will get more comments from a new set of
new set of reviewers; these comments need to be answered as in the previous reviewers; these comments need to be answered as in the previous round.
round.
What may also happen at this point, depending on the nature of your patch, What may also happen at this point, depending on the nature of your patch,
is that conflicts with work being done by others turn up. In the worst is that conflicts with work being done by others turn up. In the worst
......
...@@ -119,7 +119,7 @@ can affect your ability to get trees pulled in the future. Quoting Linus: ...@@ -119,7 +119,7 @@ can affect your ability to get trees pulled in the future. Quoting Linus:
to trust things *without* then having to go and check every to trust things *without* then having to go and check every
individual change by hand. individual change by hand.
(http://lwn.net/Articles/224135/). (http://lwn.net/Articles/224135/).
To avoid this kind of situation, ensure that all patches within a given To avoid this kind of situation, ensure that all patches within a given
branch stick closely to the associated topic; a "driver fixes" branch branch stick closely to the associated topic; a "driver fixes" branch
...@@ -138,7 +138,7 @@ When requesting a pull, be sure to give all the relevant information: where ...@@ -138,7 +138,7 @@ When requesting a pull, be sure to give all the relevant information: where
your tree is, what branch to pull, and what changes will result from the your tree is, what branch to pull, and what changes will result from the
pull. The git request-pull command can be helpful in this regard; it will pull. The git request-pull command can be helpful in this regard; it will
format the request as other developers expect, and will also check to be format the request as other developers expect, and will also check to be
sure that you have remembered to push those changes to the public server. sure that you have remembered to push those changes to the public server.
7.2: REVIEWING PATCHES 7.2: REVIEWING PATCHES
......
...@@ -6,7 +6,7 @@ This document describes how to use the dynamic debug (ddebug) feature. ...@@ -6,7 +6,7 @@ This document describes how to use the dynamic debug (ddebug) feature.
Dynamic debug is designed to allow you to dynamically enable/disable kernel Dynamic debug is designed to allow you to dynamically enable/disable kernel
code to obtain additional kernel information. Currently, if code to obtain additional kernel information. Currently, if
CONFIG_DYNAMIC_DEBUG is set, then all pr_debug()/dev_debug() calls can be CONFIG_DYNAMIC_DEBUG is set, then all pr_debug()/dev_dbg() calls can be
dynamically enabled per-callsite. dynamically enabled per-callsite.
Dynamic debug has even more useful features: Dynamic debug has even more useful features:
...@@ -26,7 +26,7 @@ Dynamic debug has even more useful features: ...@@ -26,7 +26,7 @@ Dynamic debug has even more useful features:
Controlling dynamic debug Behaviour Controlling dynamic debug Behaviour
=================================== ===================================
The behaviour of pr_debug()/dev_debug()s are controlled via writing to a The behaviour of pr_debug()/dev_dbg()s are controlled via writing to a
control file in the 'debugfs' filesystem. Thus, you must first mount the debugfs control file in the 'debugfs' filesystem. Thus, you must first mount the debugfs
filesystem, in order to make use of this feature. Subsequently, we refer to the filesystem, in order to make use of this feature. Subsequently, we refer to the
control file as: <debugfs>/dynamic_debug/control. For example, if you want to control file as: <debugfs>/dynamic_debug/control. For example, if you want to
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment