Printer-friendly version

Free lesson? Bonus!

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.

Where can you get up-to-date kernel documentation?

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 Documentation/ directory

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.

"Building" the in-kernel DocBook documentation

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.

Up-to-date kernel API documentation.

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 lib/bitmap.c:

/**
 * __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.
 */

The file 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.

The LXR Linux cross-referencer

Finally, if you want an online Linux cross referencer, you should check out http://lxr.linux.no, which should be fairly self-explanatory.