There is the Kernel Hacker's Guide. There's also a new book out by Allesandro
??
who wrote a series of excellent device driver articles for the Linux Journal
and
there is a 1.2 based Linux internals book. Additionally, I have written a
book called 'The Linux Kernel' based upon the 2.0 sources. This is on the LDP
web site. It _is_ a moving target though. Speaking of the LDP - it exists to
promote freely available Linux documentation. Help it by either (a)
contributing
new documentation or (b) reviewing existing documentation to make it better.
> : Truth is, essential documention isnt in commented code.... its exchanged
> : in email between the few knowledgeable developers and those who are
> : becoming knowledgeable.
>
> That documentation, however, goes away, and is not in an easily updatable
> format.
>
> : If we forced documentation rules, this would kill kernel developement like
> : nothing else. If you worry about docs, you arent going to bother molding
> : and shifting the code.
>
> 'Forced' was the wrong word for me to use. I appologize to the people that
> got all hyper about it. However, there may come a point in the future
> where no one is capable of "molding and shifting" a piece of code because
> no one can understand it.
>
> : Most important: Do NOT solidify an interface. Once that happens, all
> : fresh kernel developement will stop and it will merely degenerate into bug
> : fixes.
>
> Interfaces are what holds the kernel together. Now, there is a standard
> interface for allocating memory, making a process block on I/O, etc.
> These interfaces are, for the most part, solidified. Even when the
> underlying algorthims and data structures change, none of the rest of
> the code in the kernel will need to change. Now, if this already-defined
> interface were documented, new developers (and others) would know
> how to allocate memory (for instance) and have a relative degree of
> certainty that their code won't need to change in the future when we
> swith memory allocation schemes.
>
In over 3 years of kernel hacking I've seen a lot of changes. Mostly though,
the
device driver interfaces are the same. As device drivers make up around 70%
of the
kernel code this is A Good Thing (tm). The rest will change - the planned
stuff
for 2.2 is far reaching and is not evolutionary but revolutionary. The kernel
hackers will split off and form groups, each person handling their turf. The
code will be thrown (high) into the air and will land and more or less work.
It's a crazy way to work ("herding cats" was a phrase that a Debian person once
gave me, I prefer "creative anarchy") but it does work.
> : Basically: When you are busy happily hacking away... You *cant* document
> : all your changes, coz your hacks generally spread out over several time
> : periods and stretches of code.
>
> With simple revision control, you can tell in an instant exactly which
> lines in which files changed. With slightly stricter revision control,
> developers are asked to enter a short description of the changes made
> to each file. This would take a developer seconds to do, and would
> improve our ability to track bugs.
>
In code comments help you understand code. It almost never gives you the
Big Picture (tm). For that you do need seperate documentation. However, the
writer of the code is the best person for at least some initial documentation.
> : What we have now is sufficient: Someone produces a patch that
> : accomplishes a goal, with a short description of what it does. You should
> : figure out from the patch how it alters the "base" kernel.
>
> Why should we have to spend time figuring it out, when it would be ten times
> easier for the developer to tell us what changed. (See below)
>
> : I really suggest that a lot of you that have contributed to this whole
> : "documentation" thread should read the FAQ for this mailing list. It
> : should be posted shortly. When you see it posted within the next two
> : weeks, *read* it. Then you'll understand why all this rigorous
> : documentation would be more a hindrance than a help.
>
> The goal of documenting the kernel, its data structures, and algorithms,
> is to SAVE time. Not necessarily the time of the 'current' developer,
> but the time of future developers.
>
There are several classes of reader. I think that you can divide out the
curious from the kernel hackers. The curious want to know how their OS works,
how it fits together. They don't mind that the documentation is a wee bit out
of date. The hackers again divide into two camps: kernel hackers and device
driver hackers. The first can understand (had better understand) the kernel
from first principles and the second need some good documentation and a good
example device driver.
> Come on you Software Engineering students, help me out here. If a
> developer spent an extra 15 minutes documenting changes made to the code,
> it could save future developers a half or maybe an entire hour. Since
> your goal is to, as quickly as possible, add new features and fix old
> bugs in the kernel, I don't see how skipping documentation helps anyone
> in the long run.
I am a Computer Science graduate now with 15 years experience in the business.
Linux kernel development works. It has rough edges sure, but it works. The
kernel documentation is patchy but it will get there. Enough zealots will see
the need (light?). The HOWTOs are absolutely brilliant (I got IP masquarading
working in an hour last Friday). Meanwhile, there is only one person driving
the big red fire engine and that's Linus. Sometimes David (talk to us again)
Miller gets to change gear and ring the bell but the rest of us just have to
hang on as tightly as we can!
Dave