” From:
Rusty Russell [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 [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 [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
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 [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 [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 [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 [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 [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 „
Отговор
За печат
Коментар