Some entertaining lguest documentation discussed in an earlier story was merged into the mainline kernel with the commit message, "the netfilter code had very good documentation: the Netfilter Hacking HOWTO. Noone ever read it. So this time I'm trying something different, using a bit of Knuthiness." Both Netfliter and lguest, as well as the documentation for both, were written by Rusty Russell. He describes the lguest driver as, "a simple hypervisor for Linux on Linux. Unlike kvm it doesn't need VT/SVM hardware. Unlike Xen it's simply 'modprobe and go'. Unlike both, it's 5000 lines and self-contained."

Downloading the 2.6.23-rc2 kernel and looking in the "drivers/lguest/" directory I found a simple README that kicks off an interesting documentation process, beginning, "welcome, friend reader, to lguest." It goes on to note, "I can't think of many 5000-line projects which offer both such capability and glimpses of future potential; it is an exciting time to be delving into the source!" At the end of the included README is a hint as to how to find the rest of the documentation, which is embedded inline within all the lguest files. Read on to begin the exploration into lguest and its documentation.

The lguest driver is comprised of a little over a dozen files:

linux-2.6.23-rc2/drivers/lguest$ ls
core.c                  io.c     lguest_asm.S  lguest_user.c  README
hypercalls.c            Kconfig  lguest_bus.c  Makefile       segments.c
interrupts_and_traps.c  lg.h     lguest.c      page_tables.c  switcher.S

We begin by reading the included README file:

Welcome, friend reader, to lguest.

Lguest is an adventure, with you, the reader, as Hero.  I can't think of many
5000-line projects which offer both such capability and glimpses of future
potential; it is an exciting time to be delving into the source!

But be warned; this is an arduous journey of several hours or more!  And as we
know, all true Heroes are driven by a Noble Goal.  Thus I offer a Beer (or
equivalent) to anyone I meet who has completed this documentation.

So get comfortable and keep your wits about you (both quick and humorous).
Along your way to the Noble Goal, you will also gain masterly insight into
lguest, and hypervisors and x86 virtualization in general.

Our Quest is in seven parts: (best read with C highlighting turned on)

I) Preparation
	- In which our potential hero is flown quickly over the landscape for a
	  taste of its scope.  Suitable for the armchair coders and other such
	  persons of faint constitution.

II) Guest
	- Where we encounter the first tantalising wisps of code, and come to
	  understand the details of the life of a Guest kernel.

III) Drivers
	- Whereby the Guest finds its voice and become useful, and our
	  understanding of the Guest is completed.

IV) Launcher
	- Where we trace back to the creation of the Guest, and thus begin our
	  understanding of the Host.

V) Host
	- Where we master the Host code, through a long and tortuous journey.
	  Indeed, it is here that our hero is tested in the Bit of Despair.

VI) Switcher
	- Where our understanding of the intertwined nature of Guests and Hosts
	  is completed.

VII) Mastery
	- Where our fully fledged hero grapples with the Great Question:
	  "What next?"

make Preparation!
Rusty Russell.

At this point it's not immediately obvious what we're supposed to do next. However, after a few moments of thought one begins to wonder why Rusty neglected to captilize the word "make" in the final sentence of the README before his signature. A quick grep of the driver's makefile reveals that it was a very big hint:

linux-2.6.23-rc2/drivers/lguest$ grep Preparation Makefile
Makefile:Preparation Preparation!: PREFIX=P
Makefile:       @for f in Preparation Guest Drivers Launcher Host Switcher Mastery; do echo "{==- $$f -==}"; make -s $$f; done; echo "{==-==}"
Makefile:Preparation Preparation! Guest Drivers Launcher Host Switcher Mastery:

Sure enough, there's a "Preparation!" target in the makefile, and so beings an interesting documentation adventure:

linux-2.6.23-rc2/drivers/lguest$ make Preparation!
[ drivers/lguest/lguest.c ]
/*
 * A hypervisor allows multiple Operating Systems to run on a single machine.
 * To quote David Wheeler: "Any problem in computer science can be solved with
 * another layer of indirection."
 *
 * We keep things simple in two ways.  First, we start with a normal Linux
 * kernel and insert a module (lg.ko) which allows us to run other Linux
 * kernels the same way we'd run processes.  We call the first kernel the Host,
 * and the others the Guests.  The program which sets up and configures Guests
 * (such as the example in Documentation/lguest/lguest.c) is called the
 * Launcher.
 *
 * Secondly, we only run specially modified Guests, not normal kernels.  When
 * you set CONFIG_LGUEST to 'y' or 'm', this automatically sets
 * CONFIG_LGUEST_GUEST=y, which compiles this file into the kernel so it knows
 * how to be a Guest.  This means that you can use the same kernel you boot
 * normally (ie. as a Host) as a Guest.
 *
 * These Guests know that they cannot do privileged operations, such as disable
 * interrupts, and that they have to ask the Host to do such things explicitly.
 * This file consists of all the replacements for such low-level native
 * hardware operations: these special Guest versions call the Host.
 *
 * So how does the kernel know it's a Guest?  The Guest starts at a special
 * entry point marked with a magic string, which sets up a few things then
 * calls here.  We replace the native functions in "struct paravirt_ops"
 * with our Guest versions, then boot like normal. */

The "make Preparation!" target executes a shell script which extracts the above and a bit more high level documentation from the various lguest source and documentation files, dumping it all to standard out. As promised earlier in the README file, the result is an overview of the lguest code:

"I) Preparation - in which our potential hero is flown quickly over the landscape for a taste of its scope. Suitable for the armchair coders and other such persons of faint constitution."

Once you read through all the documentation presented in the Preparation section, you are steered to the next section. Each latter section offers a much deeper look at the code, along with various pieces of wit and humor thrown in for good measure, such as this from the Guest section:

"Grossly invalid calls result in Sudden Death at the hands of the vengeful Host, rather than returning failure. This reflects Winston Churchill's definition of a gentleman: 'someone who is only rude intentionally'."

Or, delving in to later sections:

"I'm told there are only two stories in the world worth telling: love and hate. So there used to be a love scene here like this:

Launcher: We could make beautiful I/O together, you and I.
Guest: My, that's a big disk!

Unfortunately, it was just too raunchy for our otherwise-gentle tale."

Further still, the documentation takes an interesting shift, "because this is in assembler rather than C, our tale switches from prose to verse." There's a brief digression as Rusty tries out limericks, haikus and Heroic Verse, ultimately settling on "something between heroic hexameter, and normal prose with inappropriate linebreaks. Anyway, it aint no Shakespeare."

The above is only a tiny sampling of the what awaits you in the lguest documentation. And to be fair, the humor and wit sampled above is only a tiny fraction of what's included, as the documentation itself is often actually quite technical and certainly useful. All said and done, it's a fun ride, and when carefully read in the order it was designed it offers excellent insight into all aspects of the lguest driver.