This is section one of the kernel mailing list FAQ and policy. This
section is posted to the linux kernel mailing list monthly. The full
FAQ is available on the world wide web on <URL:http://kernelfaq.iconsult.com/>.

Please comment on the kernel mailing list FAQ; your input will make
this document reflect the wishes of the list members exactly. Lots of
thanks to the people that already did, your comments were invaluable
for creation of this document.

Please send all communications regarding this document (such as
suggenstions, corrections etc.) to kernelfaq@iconsult.com; I'll try to include
all suggestions and corrections in the next version of the FAQ.

This is the Linux kernel mailing list FAQ and usage policy. It was
intended to be posted to the mailing list regulary. Due to its size,
only section 1 will be posted to the list, the other part is available
on the World Wide Web on <URL:http://kernelfaq.iconsult.com>. An older
version of this FAQ will be sent to new subscribers of the kernel
mailing list.

The first section contains information about the kernel mailing list.
Please read it before posting to the list to make sure you're using
everyone's time in the most efficient manner.

The FAQ is currently being reworked, the first step being a rough
translation from formatted ASCII to HTML. I'm also considering
following the necessary steps to make it an official USENET FAQ, being
posted to comp.os.linux.answers and the other appropriate *.answers
groups regulary.

Iīm sorry for not posting the document to the mailing list in june, I
didnīt want to post the full 60k document anymore and my 'real world'
work kept me from making an updated version.

If that doesn't work you probably are subscribed using another email
address than the one you're using now. In that case the first thing to
do is to find out the email address you subscribed with. (You're on
your own here, but your system administrator might help you by
checking the mail transfer agent's log files)

When you found out the address use:
(echo "unsubscribe linux-kernel" "the address you subscribed with" | mail majordomo@vger.rutgers.edu)

By the way, a small tip for mailing lists in general: On some mailing
lists the "unsubscribe <list> <address>" syntax doesn't work. In that
case use Netscape Navigator to send a mail with faked sender address:
Enter your "address you subscribed with" in Netscape's "Options/Mail
and News preferences/Your Email" field, fill in your current address
in the "Reply-to Address" and send the unsubscribe mail from Netscape.
Normally the mailing list software will believe the faked "From:"
field in the mail.

1.2. Topic

This list discusses Linux kernel development. All submissions relevant
to that, such as bug reports, enhancement ideas, kernel patches or
reports that a patch fixed a bug are appropriate. Please note the
emphasis on kernel development as opposed to development of Linux
systems in general.

1.3. Off-topic

Please do not ask basic installation or non-kernel related
configuration questions on this list. If you are unclear of the
distinction between the Linux kernel and other parts of a Linux
system, please do not post here until you have learned somewhere else;
just have a look at the Linux resources in Section 2 of this document.
In particular, if you don't know the difference between XFree86 and
the Linux kernel, please do not ask about it here. (If you don't know
what I'm talking about, this means you.)

1.4. Etiquette

As Linux grows in popularity, it is inevitable that subscriptions to
the list will greatly increase. The list is already quite large and
beginning to suffer from the classic Usenet signal to noise ratio
problem. Reading the list daily gives a sense of involvement and
excitement at being so close to the cutting edge of a compelling and
rapidly evolving technology. It is important to note that your post
will go out to many, many people and that "send" key is so very
close... A good idea to consider: "My opinions really don't matter,
but my _code_ most certainly does!" Please help us to prove that this
list can scale well to such a large audience.

1.4.1. Questions

Before posting a question to this list, think twice about whether it
is indeed kernel-related. Perhaps another newsgroup or mailing list is
better suited for the question. See Section 2 for a list of on-line
resources.

In any event have a quick look at the Documentation/Changes file, and
ensure that your software is up-to-date. Sometimes things change
within the kernel which stop user-level code from working. You'll feel
a little silly if the answer to the problem is in the documentation
that comes with the kernel, but you just didn't read it.

A good strategy is to wait a day after writing something before
posting. The very same information may hit the list during that time,
especially if the problem you are experiencing is one which many
people will find (e.g., "ps and top have stopped working!"). Probably
someone else will ask about it too; there's nothing more annoying than
seeing the same question on the list over and over again.

1.4.2. Answers

Before posting an answer to this list, also think twice! When
off-topic mail arrives (e.g., "I can't build the kernel", "how do I
convert ASCII to EBCDIC" or "Make money fast"), it is best to answer
directly (i.e., off this list). Despite our best efforts, these
questions will always appear; there is no easy way to avoid this
without moving away from creative anarchy. Dumb questions are at least
a positive sign of usage and growth. We all hate spam, but flaming to
the list just makes it worse.

Before you post an answer to a legitimate question, think twice again.
If possible try to give an answer that might help more people than the
original poster. For example posting generic strategies helps a lot of
people (especially newbies). Some great examples of such posts by
Cameron McKinnon (how to get started) and Doug Ledford (on extfs
problems) have ended up in this document.

I know all those 'think twice' are more easily said than done, but
remember _everyone_ that even tries to think will make the kernel
mailing list a more enjoyable place for all.

"Most people think about twice a year. I got famous by thinking once a
week." - George B. Shaw (see Appendix A)

1.5. Bug Reports

There are a few things to consider before reporting kernel error
messages:

Try to have a clue

A good rule of thumb that applies to everything in life - even to
linux kernel development. Think of things that might be of interest to
the developers, things that are redundant. Find out how other people's
report bugs look and what the reaction in the list is.

The developers don't have access to your system.

This means they don't have much information on how your kernel was
built, which addresses certain routines were compiled to or which
hardware you run. To get a rough idea what information might be
relevant to the developers read the following paragraphs, then have a
look at the bug report form and data collection shell script in
Appendix B.

The most complicated thing to do is to add symbolic information to
your kernel error message. Once (back in the good old days) this was
quite an ordeal, but with modern klogd/syslogd install this gets quite
easy. Make sure your kernel's System.map is installed in the right
place (/boot/System.map, /System.map or /usr/src/linux/System.map) and
from now on klogd will automatically add symbolic information to the
kernel messages it logs. See 'man klogd' to check whether the version
of klogd you run does already support that feature.

For similar functionality look at the ksymoops program in the kernel
source tree, which can be used when klogd/syslogd logged a 'raw'
kernel Oops.. message to your disk (or if you copied it down by hand,
because the system froze before being able to write to the hard disk.)

When symbolic information is added to the report you'll have to
provide everything else relevant to the problem. A general rule of
thumb is: Too much information won't hurt, not enough will. Be sure to
include at least some general description of your hardware like
processor, RAM, how many and what kind of disks, disk controllers
(IDE? SCSI?) and expansion board. In particular, make sure you mention
which kernel you are trying to use. Use the bug report form and data
collection shell script from Appendix B.

If you feel you should include your .config file, please send the
output of "grep '^[^#]' .config" instead of the whole thing, as this
saves a lot of wasted space.

The developers are busy developing

Often the developers are so busy developing, they will read your mail
but not have the time to answer it. While you might say 'it does not
take much time to answer an email' you might overlook the fact that
developers often get flooded with email, so much that they get
nightmares about it. Answering an email does in fact not take much
time, answering 100 emails does.

Trying to help the developers makes the bug vanish faster ...

If you like to be of great help to the developers you might find out
if other people have the same problem. Finding the general patterns of
a bug is a job that does not take months, and it is a job that you can
perform if you have never seen a single line of C source.

Try to find some conditions that reliably trigger the problem, this
includes asking other people if they have similar problems. If yes,
which hard- and software do they use? For example you might find out
your ext2fs file system errors are limited to users of the brand xyz
SCSI controller Mark 42. _Such_ a result will alert the developer of
the xyz SCSI driver, while a message like 'My ext2fs got bad! Linux
sucks!' probably won't.

Try to reach the appropriate people.

Sometimes it is better to communicate to the developers directly by
email instead of posting to the mailing list. See the MAINTAINERS file
in the Linux source tree to find out the maintainer for a specific
Linux subsystem. In addition, there are a number of mailing lists for
specific parts of the kernel (e.g. scsi, net, etc.); you might want to
join those lists as well, since that is where the experts hang out.

1.6. Kernel patches

A little bit of consideration first: If possible create patches that
change _one_ thing in the kernel. Doing so enables people to choose
which part of your changes they use (or even include in the
distribution kernel.) While your SCSI driver fixes might be perfectly
sane, people might not like your change to the network layers changing
network addresses from being big-endian to little-endian.

Always use unified (-u) diff format when submitting kernel patches.
The unified diff format is very readable and allows 'reverse'
application for undoing a patch (which is extremely useful when the
patch provider 'diffed' the sources the wrong way round). Oh, and
don't uuencode patches, but keep them in textual format that is
readable right there in the messages. If the patch is real big then
post the URL of the patch.

Assuming you have two source trees of the _same_ version of Linux, an
original one {original-source-tree} and one with your personal changes
{your-source-tree}, the recommended procedure for creating patch files
is:
$ make -C {original-source-tree} distclean
$ make -C {your-source-tree} distclean
$ diff -urN {original-source-tree} {your-source-tree} >/tmp/linux-patch

The patch file will then be in /tmp/linux-patch waiting to be deployed
on the Linux kernel mailing list. When posting your patch, don't
forget to mention what it does.

Of course you need to set up two identical source directories to be
able to diff the tree later. A nice trick -- it requires a little bit
of consideration, though -- is to create the 'your-source-tree' from
hard links to the 'original-source-tree':
$ tar xzvf linux-2.1.anything.tar.gz
$ mv linux linux-2.1.anything.orig
$ cp -av --link linux-2.1.anything.orig linux-2.1.anything

This will hardlink every source file from the original tree to a new
location; it is very fast, since it does not need to create more than
20 megabytes of files.

You can now apply patches to the linux-2.1.anything source tree, since
patch does not change the original files but move them to
<filename>.orig, so the contents of the hard-linked file will not be
changed.

Assuming that your editor does the same thing, too (moving original
files to backup files before writing out changed ones) you can freely
edit within the hardlinked tree.

Now the changed tree can be diffed at high speed, since most files
don't just have identical contents, they are identical files in both
trees. Naturally removing that tree is quite fast, too.

Some "nice guys" are obviously monitoring the kernel mailing list to
get email addresses. Every time I post to the mailing list I get a
bunch of "Earn $800 a week extra income" mails. Be ready to ignore or
handle this (maybe using procmail).