[META] Draft: Linux kernel mailing list policy and FAQ Draft $Revision: 1.2 $

kernelfaq@iconsult.com
4 Apr 1997 23:31:24 +0200


Linux kernel mailing list policy and FAQ Draft $Revision: 1.2 $

This is a draft for a use policy and FAQ for the kernel mailing
list. If it is accepted by the list I'd volunteer to send it to the
list regulary. The contents of this draft are taken from the linux
kernel mailing list.

I will put a HTMLized version on our web server later in the process.

Please comment on it, only your input will make this draft reflect the
wishes of the list members exactly.

When you find spelling errors or bad grammar mail corrections to
froh@iconsult.com, they will be included in the next version of the
draft. English is not my native language, so expect a lot of these.

Issues to resolve:

- Shall the FAQ be posted monthly, biweekly or weekly?
- Shall the FAQ be sent to new subscribers of the mailing list?
- I have to read up on the official quoting for URLs in plain text.
- I have perform some more research on online resources.
- Shall there be an abbreviated version of this FAQ just containing
section one? IMO people are easily scared by documents longer
than a few pages.
- Shall this article be posted to comp.os.linux.answers regulary?

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT
=======================================================================

CONTENTS

0. Introduction
1. The kernel mailing list
1.1 Topic
1.2 Off topic
1.3 Etiquette
1.4 How to get off this mailing list
2. Online resources
2.1 Kernel resources
2.2 Other points of interest
3. How to get started on kernel development
A. Appendix

0. Introduction

This is the Linux kernel mailing list use policy and FAQ. It is
posted to the mailing list regulary. When it is finished it will
be available on the world wide web.

1. The kernel mailing list

1.1. Topic

This list discusses Linux kernel development. All submissions that
help that, such as bug reports, enhancement ideas, kernel patches
or reports that a patch fixed a bug are appropriate.

1.2. Off-topic

Please do not ask basic installation questions on this list. If
you are unclear on the distinction between the Linux kernel and
other parts of a Linux system, please do not post here until you
have learned somewhere else. 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 waht I'm talking about, this
means you.)

1.3. Etiquette

Before you post a question to this list think twice if it really
is kernel related. Maybe another newsgroup or mailing list may be
better suited for the question, see below for a list of online
resources.

Befor you post an answer to this list, also think twice! When
off-topic mail arrives ("I can't build the kernel", "how to
convert ASCII to EBDIC" 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 avaid that
without moving away from creative anarchy. Dumb questions are at
least a postivive sing of usage and growth. We all hate spam, but
flaming to the list just makes it worse.

1.4. Bug Reports

Please do not report kernel Oops.. messages in raw format (without
symbolic information). Processing these messages to include the
needed information has become quite easy nowadays, by installing
the appropriate tools (current syslogd and klogd) that process is
done automatically.

It is highly recommended that you read Documentation/oops-tracing.txt

in the kernel source before posting bug reports to the kernel
mailing list. When you don't follow the instructions in that file
your bug report will probably be useless to the developers.

2. On- and offline resources

If you think that something should be listed here, please send an
email to the current list maintainer. (mailto:kernelfaq@iconsult.com)
Resources will be listed in "URL embedded in text file" syntax to
ease transition to these resources.

<Please note that I'm still in the process of collecting these,
the list is still incomplete ...>

2.1. Kernel resources

2.1.1. Linux v2 Information

(http://www.ecsnet.com)

A very useful site that lists Linux V2 information including, but
not limited to, "what's new", "how to upgrade", source code,
official and unofficial kernel patches for V2.0 and V2.1. Two
thumbs up.

2.1.2. The kernel hackers guide

(http://www.redhat.com:8080/HyperNews/get/khg.html)

Once upon a time it was a paper document but due to the 'moving
target' nature of a constantly developed kernel it now is
completley web-based, using a hyper news system so the users can
add input on it.

2.1.3. Writing device drivers

(http://www.redhat.com/~johnsonm/devices.html)

Paper to a talk by Michael K. Johnson given at Spring DECUS'95.
According to the author this probably is a bit outdated but might
be still worth reading.

2.1.4. The Linux Wish List

(http://www.cs.uml.edu/~achalan/linux/wishlist.html)

The Linux Wish List, compiled from the contents of the kernel
mailing list. Check this before posting enhancement requests to
the mailing list or to get some inspiration for your kernel
project.

2.1.5. Linux Journal

From (http://www.redhat.com:8080/HyperNews/get/devices/devices.html):

"Linux Journal (http://www.ssc.com/lj/) has had a long-running
series of articles called Kernel Korner which, despite the wacky
name, has had quite a bit of useful information on it. Some of the
articles from that column may be available on the web; most of
them are available for purchase as back issues. One particularly
useful series of articles, which focussed in far more detail than
my 30 minute talk on the subject of kernel runtime-loadable
modules, was in issues 23, 24, 25, 26, and 28. They were written
by Alessandro Rubini and Georg v. Zezschwitz. Issue 29 is slated
(as of this writing) to have an article on writing network device
drivers, written by Alan Cox. Issues 9, 10, and 11 have a series
that I wrote on block device drivers."

2.1.6. Books

There aren't any book reviews in this section yet. You might want
to look at Cameron McKinnons article in Section 4 (How to get
started on kernel development). The article discusses some books.

If you have read a book releated to Linux (or Unix) kernel
development please send a review to (mailto:kernelfaq@iconsult.com)
so it can be added to the FAQ.

2.2. Other points of interest

These are resources when you're interested in Linux
generically.

The Linux news groups:

(news://comp.os.linux.advocacy)
Benefits of Linux compared to other operating systems

(news://comp.os.linux.announce)
Announcements important to the Linux community. (Moderated)

(news://comp.os.linux.answers)
FAQs, HOWTOs, READMEs, etc. about Linux. (Moderated)

(news://comp.os.linux.development.apps)
Writing Linux applications, porting to Linux

(news://comp.os.linux.development.system)
Linux kernels, device drivers, modules

(news://comp.os.linux.hardware)
Hardware compatibility with the Linux operating system

(news://comp.os.linux.m68k)
Linux operating system on 680x0 Amiga, Atari, VME

(news://comp.os.linux.misc)
Linux-specific topics not covered by other groups

(news://comp.os.linux.networking)
Networking and communications under Linux

(news://comp.os.linux.setup)
Linux installation and system administration

(news://comp.os.linux.x)
Linux X Window System servers, clients, libs and fonts

3. How to get started on kernel development

Cameron MacKinnon (mailto:mackin@interlog.com) wrote a wonderful
article on that topic:

"... I'm not a pro, but I generally know what's going on for
least part of the time. Here's what I did:

I bought books. Here's reviews: LINUX Kernel Internals, Beck et
al, Addison Wesley, 0-201-87741-4. I read about a third of
it. It's dated (1.2 kernels) and doesn't have anything about
SCSI in it, but it's the only Linux kernel book out
there. There's a new version out for 2.0 kernels, but only in
the original German. 'The Design and Implementation
of the 4.4 BSD Operating System', McKusick et al, Addison Wesley,
0-201-54979-4. A much more readable book, IMHO. It talks about the BSD
design in general, why things changed over time, why and how specific
performance tradeoffs were made, etcetera. Also, 'The Magic Garden
Explained' or something like that, borrowed, pub. and ISBN unknown. This
book is a very thorough coverage of the design of System 5 Release 4
(SVR4), but not as easy to read as the BSD book. Bottom line: Beg,
borrow, check out or steal one book, any book, on the design of the UNIX
operating system. Sit in a library or a bookstore reading it, if you
haven't got the money. You need to understand how schedulers, pagers,
swappers, top and bottom halves, wait queues, inodes, ttys, the boot
process, init and some other stuff work. Most of this stuff will be
applicable to Linux at the concept level, regardless of the book (ignore
anything on SysV STREAMS). Unless you're extremely gifted, the concepts
won't reveal themselves to you from kernel source code. LEARN THE
CONCEPTS. The Linux community is not a good place to do this - this list
assumes that if you're here, you already know them. If you're one of
those truly unlucky people with no access to such a book, try to find
this info on the net. I've never really looked. If all else fails,
proceed to step two:

I read Michael Johnson's Kernel Hackers' Guide. It wasn't perfect when I
read it, but that was a while ago. 1) It's probably perfect by now. 2)
It's free. You can get it anywhere, including here:
http://www.redhat.com:8080/HyperNews/get/khg.html
It does a good job of mapping the concepts you just learned to actual
kernel function calls and processes in Linux. Also, many kernel
functions have man pages, though they're horribly out of date.

I subscribed to mailing lists. Initially I was all over: gcc, kernel, a
few scsi lists, security... Now I've got it down to a core of kernel,
two SCSI driver lists, DIALD, security and SMP. Don't be afraid to
subscribe to a lot of lists (read-only!) for a few weeks to see what
interests you. You can always unsubscribe later. Some people prefer
reading the lists via news, but I'd recommend mail: You SAVE the mail on
your hard disk. It becomes your personal reference library (N.B. UNIX
has some really great text search and processing tools). You read all
the mail. This gives you a feel for what's being worked on and what's
not, who knows what they're talking about and who doesn't, and what
snags are troubling other users. This is important so you can ask senior
developers PRIVATELY when you have questions relating to The Code -
unless you genuinely believe that a lot of list subscribers also want
the answer. Also, some of the news gateways appear to be brutally
broken, randomly mixing messages from different linux lists like a
cypherpunk remailer gone mad. I recommend going straight to the source:
send 'help' to mailto:majordomo@vger.rutgers.edu

I quickly got over the idea that I could learn everything about the
kernel. Last time I looked, it was over 600,000 lines of source. I can
muck around with SCSI and network device drivers, I understand the mid
level SCSI code, and I've got a reasonably good handle on the scheduler.
That leaves high level networking, filesystems, the buffer cache and
memory management, to name a few, ABOUT WHICH I HAVEN'T A CLUE. Pick an
area you want to diddle with, and concentrate on that. If you don't
believe me, grab a dictionary and look up 'hubris'.

I read most (some?) of the important stuff in Documentation/ (you should
read it all) and then: I dove into the code, wholeheartedly, for nights
(days?) at a time. Pick drivers. Concentrate on the simple ones - you
want concepts, not nasty workarounds for buggy hardware. Try 'wc
*.c|sort' in your favourite directory. Pick ones that look well
formatted and well commented, and see how they're written and how they
interact with the higher level stuff. Go into each subdirectory in the
whole linux/ tree, and learn what lives there. You should be able to
identify what's what from the stuff you read in those books. Note
especially mm/ and kernel/, along with their counterparts under arch/.
Here lie most of the important functions for juggling memory,
interrupts, processes etcetera. Learn to use grep, find and xargs
effectively. If you have a strong constitution, look in the scripts/
directory and the Makefiles everywhere to see how the kernel actually
gets built. If you're a bit twiddler at heart, look at the low level
stuff for your favourite architecture under arch/.

If you've still got the lust for knowledge at this point, you will
probably have found 'that special something' that interests you in the
kernel. You will know generally how things work from the source, and you
will know the right people to ask from the source and the mailing lists.
If you have a question, go ahead and ask it. I've found developers to be
very helpful when asked questions by someone who's obviously studied the
sources. Play around. Recompile. Benchmark. Test.

One thing that's probably overlooked by a lot of Linux people: BSD, 'the
other free UNIX'. I can't even tell you the difference between FreeBSD
and NetBSD, but for my purposes, I don't care. They're available free on
the net or a CD, just like Linux (http://ftp.freebsd.org and
http://www.freebsd.org). If you're stumped by something in Linux, seeing
how BSD does it is often helpful, especially for device drivers. Also
(ahem) BSD code sometimes seems to be commented and formatted somewhat
better. I don't run it, I just look at the source.

At this stage your hats will no longer fit, and your dog will have run
off with your girlfriend. No matter, because you'll be able to ask, and
sometimes answer, intelligent questions about kernel design, in your
particular specialty areas. You'll be fixing insidious bugs, improving
performance, and posting things like 'this patch is from memory and
untested, but it will solve your problem on 2.1.87: [proper patch
syntax]'

I'm not at this stage yet, and I've been working at it for a while.
That's why I usually post answers to questions like 'where do I begin'
rather than 'why did it hang'. The above is working for me, it might
work for you. May the Source be With You, Always."

5. How do I get off this mailing list ???

Send a mail containing "unsubscribe linux-kernel" to
majordomo@vger.rutgers.edu

(echo "unsubscribe linux-kernel" | mail majordomo@vger.rutgers.edu)

A. Appendix A - Maintainers

This policy and FAQ is currently maintained by Frohwalt Egerer
(mailto:froh@iconsult.com). For communication concerning this
document please use (mailto:kernelfaq@iconsult.com), that mail
alias will always point to the current maintainer.

The policy is created from input on the linux kernel mailing list.
If desired by members of the list a voting will be performed to
ratify the policy.

Thanks to David A Rusling (mailto:rusling@linux.reo.dec.com) for
providing the foundation to section one. Thanks to Colin Plumb
(mailto:colin@nyx.net) who refined my proposal for section one
using his fine taste of language.

Thanks to Cameron MacKinnon (mailto:mackin@interlog.com) for his
really great article on getting stared with kernel development
which I adopted into this document.

And thanks to W. Reilly Cooley, Eric Hoeltzel, Kevin Fenzi,
Gabriel Paubert, Marc Merlin, Tethys "SYSTEM ADMIN" X,
Antoine Reid and marcl@magic.metawire.com for their input and
suggestions.