These are diffs for the current version of the FAQ. To access the full
faq please have a look at <URL:http://kernelfaq.iconsult.com/>
The full FAQ will be posted to the Linux kernel mailing list regulary
after it settled down a bit.
The FAQ on the web server is the pure ASCII FAQ, I will create a
HTMLized version later.
Please comment on the current changes; your input will make this draft
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.
If you find spelling errors or bad grammar, please mail corrections to
kernelfaq@iconsult.com, and they will be included in the next version
of the draft.
Issues to resolve:
- Is the attribution to George B. Shaw in Section 1.4 correct? I
heard it in German on TV , remembered it for a few weeks and
translated it from memory. I'd be grateful if some nice soul
informed my <URL:mailto:kernelfaq@iconsult.com> about the
original wording and place where to find it.
- Do people like the bug report form in Appendix B?
- Which testing tools for detecting hardware problems (besides
memtest-86) are available? Commercial ones? Free ones? Ones that
run on other operating systems?
- What is the recommended diff procedure for kernel patches?
I'd use something like
diff -r -u -N <old-kernel-source-directory> <new-kernel-source-directory>
but please comment on this. I'd also appreciate any short shell
scripts that ease creating patches for kernel trees.
Resolved issues (please still comment on those ...)
- Would a 'kernel mailing list bug report form' be a good idea? It
would ask questions regarding the hard- and software of the buggy
system. (Maybe a shell script that collects information from /proc
and automatically includes it in the bug report would be cool.)
-> A first draft of such a form is included as Appendix B
- Shall the FAQ be sent to new subscribers of the mailing list?
-> I'll contact the mailing list maintainer when the FAQ is
finished and ask him to configure majordomo to send the
document to new subscribers of the list.
- Shall this article be posted to comp.os.linux.answers regularly?
-> Yes, it will be posted there, as well as in all other
appropriate *.answers newsgroups.
- Shall the FAQ be posted monthly, biweekly or weekly?
-> Most answers I got prefer biweekly, but now people start to get
unhappy by the size of this document. This is closely linked
with the next question.
- Shall there be an abbreviated version of this FAQ just containing
section one?
-> The answers I got suggested not to do so. I still favor the
idea of having a _short_ mailing list policy document. The
final decision should be postponed until the first 'release'
version of this FAQ is finished.
-> The answers I'm getting _now_ (as we gout around 1000 lines)
recommend doing so.
Index: draft
===================================================================
RCS file: /usr/local/cvs_repository/repository/list-faq/draft,v
retrieving revision 1.7
diff -u -r1.7 draft
--- draft 1997/04/07 04:32:48 1.7
+++ draft 1997/04/07 05:39:52
@@ -45,8 +45,11 @@
= 0. = Introduction
This is the Linux kernel mailing list FAQ and usage policy. It is
- posted to the mailing list regularly. Note that the FAQ is not so
- much a FAQ but more a 'Frequent answers collection'.
+ posted to the mailing list regularly. On the World Wide Web it is
+ available on http://kernelfaq.iconsult.com
+
+ Note that the FAQ is not so much a FAQ but more a collection of
+ "frequent answers".
The first section contains information about the kernel mailing list.
Please read it before posting to the list or be ready to be
@@ -57,8 +60,9 @@
= 1.1. = How do I get off of this mailing list ???
- Send mail containing "unsubscribe linux-kernel" to
- majordomo@vger.rutgers.edu
+ Send mail containing "unsubscribe linux-kernel" (without the quote
+ marks) in the body of the message (not the subject line) to
+ majordomo@vger.rutgers.edu.
(echo "unsubscribe linux-kernel" | mail majordomo@vger.rutgers.edu)
@@ -82,6 +86,18 @@
= 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 involvment
+ 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.
+
- Questions
Before posting a question to this list, think twice about
@@ -125,37 +141,33 @@
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.
-
- There's a saying that is attributed to George B. Shaw:
+ mailing list a more enjoyable place for all.
"Most people think about twice a year. I got famous by thinking
- once a week."
+ once a week." - George B. Shaw (see Appendix A)
- (I heard this on TV in German, remembered it for a few weeks and
- translated it from memory. I'd be grateful if some nice soul
- informed <URL:mailto:kernelfaq@iconsult.com> me about the
- original wording and place where to find it.)
= 1.5. = Bug Reports
There are a few things to consider before reporting kernel error
messages:
- - Think twice!
+ - 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 and even
- that a bug reporter trying to be too clever optimized away that
- bit of relevant information. Find out how other people's report
- bugs look and what the reaction in the list is.
+ 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.
+ 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)
@@ -164,7 +176,8 @@
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'.
+ 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
@@ -179,7 +192,8 @@
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. 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,
@@ -258,6 +272,12 @@
<URL:http://www.caldera.com/LDP/Kernel-HOWTO.html>
<URL:http://sunsite.unc-edu/LDP/Kernel-HOWTO.html>
+ If you are looking for all the other HOWTOS and mini-HOWTOS just
+ check out LDP itself:
+
+ <URL:http://www.caldera.com/LDP/>
+ <URL:http://sunsite.unc-edu/LDP/>
+
= 2.1.2. = Linux v2 Information
<URL:http://www.linuxhq.com>
@@ -290,6 +310,12 @@
word "lists". Some of the lists are mentioned in the MAINTAINERS
file in the Linux source code.
+ Having a close look at the linux-admin list would be
+ worthwile. Many of the off-topic questions on linux-kernel are
+ appropriate for linux-admin and the latter list seems to be pretty
+ well behaved. The admin list is approaching the amount of traffic
+ on the kernel list.
+
= 2.1.5. = Writing device drivers
<URL:http://www.redhat.com/~johnsonm/devices.html>
@@ -311,23 +337,11 @@
- Linux Journal
- From <URL:http://www.redhat.com:8080/HyperNews/get/devices/devices.html>:
-
- "Linux Journal <URL: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 in 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."
+ <URL:http://www.ssc.com/lj/>
- The four articles on writing runtime-loadable character device
+ Linux Journal has had a long-running series of articles called
+ Kernel Korner which, has had quite a bit useful information in
+ it. Four articles on writing runtime-loadable character device
drivers in issues 23 - 26 have been made available on Linux
Journal's WWW Site:
@@ -338,17 +352,14 @@
= 2.1.8. = Books
- There aren't any book reviews in this section yet. You might want
- to look at Cameron McKinnon's article in Section 4 (How to get
- started on kernel development). That article discusses some books.
-
- If you have read a book related to Linux (or Unix) kernel
- development please send a review to <URL:mailto:kernelfaq@iconsult.com>
- so it can be added to the FAQ.
-
- You might have a look at the Linux Reading List Mini-HOWTO, which
- although being a bit dated list a lot of the books useful to kernel
- programmers.
+ There aren't any book reviews in this section, just pointers to
+ those. First you might want to look at Cameron McKinnon's article
+ on geting started with kernel development, which also mentions
+ some books.
+
+ The next place to stop is the Linux Reading List Mini-HOWTO, which
+ although being a bit dated list a lot of the books useful to
+ kernel programmers:
<URL:http://www.caldera.com/LDP/HOWTO/mini/Reading-List>
<URL:http://sunsite.unc.edu/LDP/HOWTO/mini/Reading-List>
@@ -395,6 +406,9 @@
irc.linpeople.org (207.16.36.11) or vinge.linpeople.org. Look for
the channels #help or #natter.
+ Also irc.blackdown.org is a good place for advanced topics and
+ kernel hackers.
+
An IRC client is required to connect to the many IRC networks
available on the Internet. A goot place to find IRC clients is:
@@ -508,19 +522,17 @@
"On a block device (block size 1024 bytes) with ext2fs, I don't
reliably get back from a file what I first wrote in."
- Before starting another round on the ext2fs file corruption thread
- in the kernel mailing list you might want to check all other
- possible sources. Often a 'Linux sucks' thread ends with the
- original poster finding a problem with his computer's hardware or
- software installation.
-
- For example I had a problem with ext2fs file system corruption
- once myself. Asking on the linux newsgroups I found out others had
- experienced similar problems, and all had a common factor: The
- same brand and model of hard drive. My (then) brand new Conner
- CFP1060S had a firmware bug. Discussing this with other people
- that had the same problem was the way to find a hard to locate bug
- in the drive's firmware.
+ Normally any kind of file system corruption is a sign of hardware
+ problems or problems with a low level I/O driver. Ext2fs is a
+ quite tested and stable file system, but due to its high
+ performance it is likely to dig out problems in the lower levels
+ of the system.
+
+ When I experienced ext2fs file system corruption myself, a query
+ on the linux newsgroups showed others had experienced similar
+ problems. It turned out to be a firmware problem in the Conner
+ CFP1060S hard drive, when data was read _really fast_ the buffer
+ cache algorithm in the drive firmware failed.
There are a lot of things to try when you get ext2fs corruption:
@@ -680,19 +692,6 @@
to be reliable and leaving fast code in place, you've slowed
the code down so it doesn't break your faulty hardware."
- I'd like to add some real life examples to the last sentence of
- Doug's article: In the case of the faulty drive firmware
- mentioned above slowing down e2fsck (by deliberately adding
- delays it at strategic places in the e2fsck source) the problem
- vanished. In the project I earn money with I had a similar
- example right this week. (A terminal adapter that drops all
- received characters for a few milliseconds after a CONNECT
- response. On Solaris the problem went unnoticed due to Solaris
- being not exactly fast regarding character I/O. This resulted in
- a 'Linux sucks!' situation; a certain software just refused to
- work on Linux, because of its data stream being converted to
- bogons in some device connected to the serial port.)
-
- Use debugging tools to check your system.
Memtest-86, a thorough, stand alone memory tet for 386, 486 and
@@ -875,22 +874,42 @@
excellent description on how to hunt down filesystem corruption
problems.
- And thanks to W. Reilly Cooley, Eric Hoeltzel, Kevin Fenzi,
- Gabriel Paubert, Marc Merlin, Tethys "System Admin" X, Antoine
- Reid, Sebastian Benoit, Regis Duchesne, Riccardo Facchetti,
- J. Sean Connel, Seth M. Landsman, Martin Radford, James Mastros,
- Nicholas J. Leon, E.Rodichev, Antoine Reid, Ben Clifford, Melissa
- Johnson, Dave Wreski, Greg Patterson, Keith Rohrer, Roch-Alexandre
- Nomine-Beguin and all that I forgot to mention for their input,
+ Thanks to Eric Hoeltzel <URL:mailto:eric@dogbert.sitewerks.com>
+ for the enormous amount of suggestions.
+
+ Thanks to Evgeny Rodichev <URL:maito:er@sai.msu.su> for providing
+ the ver_linux shell script.
+
+ And thanks to W. Reilly Cooley, Kevin Fenzi, Gabriel Paubert, Marc
+ Merlin, Tethys "System Admin" X, Antoine Reid, Sebastian Benoit,
+ Regis Duchesne, Riccardo Facchetti, J. Sean Connel, Seth
+ M. Landsman, Martin Radford, James Mastros, Nicholas J. Leon,
+ E.Rodichev, Antoine Reid, Ben Clifford, Melissa Johnson, Dave
+ Wreski, Greg Patterson, Keith Rohrer, Roch-Alexandre
+ Nomine-Beguin, Raymo <slk9q@cc.usu.edu>, Elliot Lee, Greg
+ Alexander and all that I forgot to mention for their input,
suggestions and articles on the mailing list. This FAQ would not
exist without their help.
+ I heard the quote of George B. Shaw on German TV, remembered it
+ for a few weeks and translated it back to English for this FAQ. It
+ might therefor not be accurate.
+
= B. = Appendix B - Linux Kernel Mailing List Bug Report Form
Please use the following form to report bugs to the Linux kernel
- mailing List. Fill in the data as necessary, and post it to the
- mailing list with a subject of the form "ISSUE: <one lime summary
- from [3.]" for easy identification by the developers
+ mailing list. Having a standardized bug report form makes it
+ easier for you not to overlook things, and easier for the
+ developers to find just the little tad of information they're
+ really interested in.
+
+ First run the ver_linux script included at the end of this
+ Appendix or at <URL:ftp://ftp.sai.msu.su//sai2/ftp/pub/Linux/ver_linux>
+ It checks out the version of some important subsystems.
+
+ Use that information to fill in all fields of the bug report form,
+ and post it to the mailing list with a subject of "ISSUE: <one
+ lime summary from [3.]>" for easy identification by the developers
[1.] Your Email Address:
[2.] Your Name:
@@ -898,11 +917,7 @@
[4.] Keywords (i.e., modules, networking, kernel):
[5.] Kernel version (from /proc/version):
[6.] Environment
- [6.1.] Kernel build utilities
- [6.1.1.] Version of gcc in use (from gcc -V):
- [6.1.2.] Version of ld.so in use:
- [6.1.3.] Version of binutils in use:
- [6.1.4.] Version of libc in use:
+ [6.1.] Software (add the output of the ver_linux script here)
[6.2.] Processor information (from /proc/cpuinfo):
[6.3.] Module information (from /proc/modules):
[6.4.] SCSI information (from /proc/scsi/scsi):
@@ -914,6 +929,34 @@
(see Kernel Mailing List FAQ, Section 1.5):
[X.] Other notes, patches, fixes, workarounds:
+
+ ver_linux (by Evgeny Rodichev <URL:mailto:er@sai.msu.su>
+
+ #!/bin/sh
+ echo '-- Versions installed: (if some fields are empty or looks'
+ echo '-- unusual then possibly you have very old versions)'
+ uname -a
+ insmod -V 1>/tmp/ver_linux.tmp 2>>/tmp/ver_linux.tmp
+ awk 'NR==1{print "Kernel modules ",$NF}' /tmp/ver_linux.tmp
+ rm /tmp/ver_linux.tmp
+ echo "Gnu C " `gcc --version`
+ ld -v | awk -F\) '{print $1}' | awk '{print "Binutils ",$NF}'
+ ls -l /usr/lib/libc.so | awk -F. '{print "Linux C Library " $4"."$5"."$6}'
+ ldd -v | awk '{print "Dynamic Linker (ld.so)", $3}'
+ ls -l /usr/lib/libg++.so | awk -F. '{print "Linux C++ Library " $4"."$5"."$6}'
+ ps --version | awk '{print "Procps ", $3}'
+ mount --version | awk -F\- '{print "Mount ", $NF}'
+ netstat --version | awk \
+ 'NR==1{if ($5 != "") { n=split($5,buf,"-"); ver=buf[n]; done=1 }}
+ NR==2{if (done != 1) ver=$3 }
+ END{print "Net-tools ",ver}'
+ loadkeys -h 2>&1 | awk 'NR==1{print "Kbd ",$3}'
+ expr --v | awk '{print "Sh-utils ", $NF}'
+
+ (Note: On my system I had some strage results with that script,
+ but I added it unchanged to this version of the FAQ. The script
+ will probably be changed and expanded in one of the next
+ versions. -- Froh)
= C. = Appendix C - Change Log