"Lguest is an adventure, with you, the reader, as Hero," began some documentation for lguest recently submitted by Rusty Russell. The documentation continued, "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."
Andrew Morton noted that he would consider the documentation patches for inclusion in the 2.6.23 kernel, to which Rusty replied, "indeed, no code changes, and I feel strongly that it should go into 2.6.23 because it's *fun*. And (as often complained) there's not enough poetry in the kernel." Linus Torvalds quipped, "there's a reason for that," going on to rhyme, "there once was a lad from Braidwood, with a wife and a hatred for FUD, he hacked kernels for fun, couldn't get them to run, but he always felt that he should." He added, "so when you say 'there's not enough poetry', next time you'll know why. You *really* don't want want poetry." This led to numerous additional poetic submissions about which Rusty noted, "there was a poetic infection, which distorted the kernel's direction, the code got no time, as they all tried to rhyme, and it shipped needing lots of correction."
From: Rusty Russell [1] [email blocked] To: Linus Torvalds [email blocked] Subject: [PATCH 1/7] lguest: documentation pt I: Preparation Date: Sat, 21 Jul 2007 11:17:58 +1000 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. Start with drivers/lguest/README. Signed-off-by: Rusty Russell [email blocked] --- Documentation/lguest/extract | 58 +++++++++++++++++++++++++++++++++ Documentation/lguest/lguest.c | 9 +++-- drivers/lguest/Makefile | 12 ++++++ drivers/lguest/README | 47 ++++++++++++++++++++++++++ drivers/lguest/core.c | 7 ++- drivers/lguest/hypercalls.c | 9 +++-- drivers/lguest/interrupts_and_traps.c | 13 +++++++ drivers/lguest/io.c | 8 +++- drivers/lguest/lguest.c | 30 +++++++++++++++-- drivers/lguest/lguest_bus.c | 3 + drivers/lguest/lguest_user.c | 7 +++ drivers/lguest/page_tables.c | 10 ++++- drivers/lguest/segments.c | 11 ++++++ drivers/lguest/switcher.S | 13 +++---- 14 files changed, 218 insertions(+), 19 deletions(-)
From: Andrew Morton [2] [email blocked] To: Rusty Russell [email blocked] Subject: Re: [PATCH 1/7] lguest: documentation pt I: Preparation Date: Mon, 23 Jul 2007 17:12:38 -0700 On Sat, 21 Jul 2007 11:17:58 +1000 Rusty Russell [email blocked] wrote: > 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. Start with drivers/lguest/README. um. I'm OK with merging patches and given lguest's newness, the timestamp on these patches, the fact that they don't change code generation (right?) and my reluctance to carry large do-nothing patches for two months, I'd be OK with squeaking them into 2.6.23. But I worry that you're proposing adding what appears to be new Documentation-related machinery and infrastructure when there's already increased activity in that area from other people and we might all be headed in different directions and stuff. So first I think we'd best form a kernel kommittee and mull this for a while (preferably months) to screw you around as much as poss, OK? ;) Items for consideration would be: - if this stuff is good, shouldn't other code be using it? If so, is this new infrastructure in the correct place? - if, otoh, this infrastructure is _not_ suitable for other code, well, what was wrong with it? - if the requirement is good, perhaps alternative implementations should be explored (dunno what). IOW, I'd be interested in hearing Rob and Randy's opinions on it all, please.
From: Rusty Russell [3] [email blocked] To: Andrew Morton [email blocked] Subject: Re: [PATCH 1/7] lguest: documentation pt I: Preparation Date: Tue, 24 Jul 2007 11:01:48 +1000 On Mon, 2007-07-23 at 17:12 -0700, Andrew Morton wrote: > On Sat, 21 Jul 2007 11:17:58 +1000 > Rusty Russell [email blocked] wrote: > > > 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. Start with drivers/lguest/README. > > um. > > I'm OK with merging patches and given lguest's newness, the timestamp on > these patches, the fact that they don't change code generation (right?) and > my reluctance to carry large do-nothing patches for two months, I'd be OK > with squeaking them into 2.6.23. Indeed, no code changes, and I feel strongly that it should go into 2.6.23 because it's *fun*. And (as often complained) there's not enough poetry in the kernel. > But I worry that you're proposing adding what appears to be new > Documentation-related machinery and infrastructure when there's already > increased activity in that area from other people and we might all be > headed in different directions and stuff. It does add an lguest-specific script: I aimed for the minimal documentation script required to weave the code and documentation (basically extracts and orders by comment prefix, because code order isn't the same as optimal documentation order). This is great for lguest, where the entire codebase is small and self-contained enough to be woven into a narrative, and the maintainer is prepared to put in the cycles to keep it uptodate. But writing this documentation took *weeks*, to document 5000 lines of code. Perhaps this effort, if merged, will inspire others, but I've seen little indication so far: we have enough trouble getting them documenting a single public function. > IOW, I'd be interested in hearing Rob and Randy's opinions on it all, > please. So they can see what we're talking about, here's an example of the output: http://lguest.ozlabs.org/lguest-journey.c.bz2 [4] Cheers, Rusty.
From: Linus Torvalds [email blocked] To: Rusty Russell [email blocked] Subject: Re: [PATCH 1/7] lguest: documentation pt I: Preparation Date: Mon, 23 Jul 2007 18:18:33 -0700 (PDT) On Tue, 24 Jul 2007, Rusty Russell wrote: > > Indeed, no code changes, and I feel strongly that it should go into > 2.6.23 because it's *fun*. And (as often complained) there's not > enough poetry in the kernel. There's a reason for that. There once was a lad from Braidwood With a wife and a hatred for FUD He hacked kernels for fun, couldn't get them to run. But he always felt that he should. See? So when you say "there's not enough poetry", next time you'll know why. You *really* don't want want poetry. Linus PS. Nothing rhymes with Ballalaba.
From: Rusty Russell [5] [email blocked] To: Linus Torvalds [email blocked] Subject: Re: [PATCH 1/7] lguest: documentation pt I: Preparation Date: Tue, 24 Jul 2007 11:51:19 +1000 On Mon, 2007-07-23 at 18:18 -0700, Linus Torvalds wrote: > > On Tue, 24 Jul 2007, Rusty Russell wrote: > > > > Indeed, no code changes, and I feel strongly that it should go into > > 2.6.23 because it's *fun*. And (as often complained) there's not > > enough poetry in the kernel. > > There's a reason for that. > > There once was a lad from Braidwood > With a wife and a hatred for FUD > He hacked kernels for fun, > couldn't get them to run. > But he always felt that he should. > > See? There once was a virtualization coder, Whose patches kept getting older, Each time upstream would drop, His documentation would slightly rot, SO APPLY MY FUCKING PATCHES OR I'LL KEEP WRITING LIMERICKS. Thanks! Rusty.
From: Alan Cox [6] [email blocked] To: Rusty Russell [email blocked] Subject: Re: [PATCH 1/7] lguest: documentation pt I: Preparation Date: Tue, 24 Jul 2007 10:52:08 +0100 Windsor, Berkshire, SL4 1TE, Y Deyrnas Gyfunol. Cofrestrwyd yng Nghymru a Lloegr o'r rhif cofrestru 3798903 > There once was a virtualization coder, > Whose patches kept getting older, > Each time upstream would drop, > His documentation would slightly rot, > SO APPLY MY FUCKING PATCHES OR I'LL KEEP WRITING LIMERICKS. There once was a man they called rusty Who patches were terribly crusty Though his patches were right And Linus was bright They sat on the list getting dusty.
From: Rusty Russell [7] [email blocked] To: Alan Cox [email blocked] Subject: Re: [PATCH 1/7] lguest: documentation pt I: Preparation Date: Tue, 24 Jul 2007 20:28:14 +1000 On Tue, 2007-07-24 at 10:52 +0100, Alan Cox wrote: > > There once was a virtualization coder, > > Whose patches kept getting older, > > Each time upstream would drop, > > His documentation would slightly rot, > > SO APPLY MY FUCKING PATCHES OR I'LL KEEP WRITING LIMERICKS. > > There once was a man they called rusty > Who patches were terribly crusty > Though his patches were right > And Linus was bright > They sat on the list getting dusty. There was a poetic infection Which distorted the kernel's direction, The code got no time As they all tried to rhyme And it shipped needing lots of correction.
From: Alan Cox [8] [email blocked] To: Rusty Russell [email blocked] Subject: Re: [PATCH 1/7] lguest: documentation pt I: Preparation Date: Tue, 24 Jul 2007 13:04:23 +0100 Windsor, Berkshire, SL4 1TE, Y Deyrnas Gyfunol. Cofrestrwyd yng Nghymru a Lloegr o'r rhif cofrestru 3798903 On Tue, 24 Jul 2007 20:28:14 +1000 Rusty Russell [email blocked] wrote: > On Tue, 2007-07-24 at 10:52 +0100, Alan Cox wrote: > > > There once was a virtualization coder, > > > Whose patches kept getting older, > > > Each time upstream would drop, > > > His documentation would slightly rot, > > > SO APPLY MY FUCKING PATCHES OR I'LL KEEP WRITING LIMERICKS. > > > > There once was a man they called rusty > > Who patches were terribly crusty > > Though his patches were right > > And Linus was bright > > They sat on the list getting dusty. > > There was a poetic infection > Which distorted the kernel's direction, > The code got no time > As they all tried to rhyme > And it shipped needing lots of correction. Dear Rusty I think that we know Your code has good things to show But an unreliable guide To the poetic aside Would probably steal the show
From: Alan Cox [9] [email blocked] To: Linus Torvalds [email blocked] Subject: Re: [PATCH 1/7] lguest: documentation pt I: Preparation Date: Tue, 24 Jul 2007 10:33:25 +0100 Windsor, Berkshire, SL4 1TE, Y Deyrnas Gyfunol. Cofrestrwyd yng Nghymru a Lloegr o'r rhif cofrestru 3798903 > So when you say "there's not enough poetry", next time you'll know why. > You *really* don't want want poetry. That isn't poetry. We'll be doing Finnish jokes next 8). I'm also not sure that kernel documentation in rhyme is the best idea: --------------- Ah look at all the laundered pages Ah look at all the laundered pages Handling Pages Pick up the list and the link where kswap has been A paging scheme Runs down the I/O Watching the queues that now keep me a list of the store Who is it for All the laundered pages Where do they all come from All the laundered pages Where do they all belong Meeting bdflush Writing the pages of a disk file that no one will clear No task comes near Look at it working Sleeping a lot in the night when there's no pressure there What does it care All the laundered pages Where do they all come from All the laundered pages Where do they all belong Ah look at all the laundered pages Ah look at all the laundered pages Oracle DB Died under load and was freed along with its name No admin came Good old bdflush Wiping the dirt from the pages as it walks down the chain Nothing was aged All the laundered pages (Ah look at all the laundered pages) Where do they all come from All the laundered pages (Ah look at all the laundered pages) Where do they all belong
Related Links:
- Archive of above thread [10]
- KernelTrap interview with Rusty Russell [11]
- KernelTrap interview with Andrew Morton [12]
- KernelTrap interview with Alan Cox [13]