Occasionally, in the midst of this Linux kernel programming course, I'll want to throw out a tidbit that's technically not a lesson in kernel programming but which I think will have some value, so I'll just put it in where I think it's appropriate and make it readable by everyone. It's just a freebie and doesn't count against the total number of lessons in the course. There will probably be another one of these shortly before we get back to subscriber-only content.
You might have noticed in your travels through Linux kernel land that it's not easy to find truly current documentation that reflects the state of the kernel in the current development tree, but there are some options you should know about.
The first recommendation anyone ever gets is to peruse the
Documentation/ directory that's part of the kernel source tree itself. While that's a good place to start, that directory has the same drawback as most kernel documentation in that it contains quite a lot of aging or obsolete information, so treat what you see there appropriately skeptically.
However, there is a
Documentation/ subdirectory you should know about.
If you look closely, you'll notice a directory of DocBook-format content,
Documentation/DocBook/, with "tmpl"-format document files. And if, from the top level of the source tree, you run
make help, you can see that there are a number of targets for rendering that content into various readable formats:
$ make help ... Documentation targets: Linux kernel internal documentation in different formats: htmldocs - HTML pdfdocs - PDF psdocs - Postscript xmldocs - XML DocBook mandocs - man pages installmandocs - install man pages generated by mandocs cleandocs - clean all generated DocBook files ...
Thus, if you wanted to build readable HTML files out of all that documentation template info, you'd simply run:
$ make htmldocs
Note that, depending on the output format you're generating, you'll need the appropriate packages. For HTML, you'll probably need whatever corresponds to the libxml2, xsltproc and xmlto packages for your distribution. For PDF, you'll need even more, specifically an FO processor like FOP. So let's keep it simple and stick with HTML output for now.
Exercise for the student: Build all of the HTML output, and leave a comment regarding any packages you found it necessary to install. If the build succeeds, your
Documentation/DocBook should now be full of HTML files at which you can point a browser and start reading.
But wait ... there's more.
Even though all of that DocBook documentation is part of the kernel source tree, it suffers from exactly the same flaw as any other kernel documentation -- if it's neglected, it will also get out of date. But there's one bit of documentation that should stay current, and that's because it's generated dynamically from the actual source.
That would be the
kernel-api documentation, which is built from rummaging through the kernel source tree and collecting all inline documentation. Here's a sample of that "inline" documentation from the library source file
/** * __bitmap_shift_left - logical left shift of the bits in a bitmap * @dst : destination bitmap * @src : source bitmap * @shift : shift by this many bits * @bits : bitmap size, in bits * * Shifting left (multiplying) means moving bits in the LS -> MS * direction. Zeros are fed into the vacated LS bit positions * and those MS bits shifted off the top are lost. */
kernel-api.tmpl defines all files and directories examined for this inline documentation, collects all of it and renders it into (in this case) HTML so that you can browse it at your leisure.
Finally, if you want an online Linux cross referencer, you should check out http://lxr.linux.no, which should be fairly self-explanatory.