OSDL to fund a kernel tech writer [LWN.net]

OSDL to fund a kernel tech writer

Posted Nov 8, 2006 18:43 UTC (Wed) by MisterIO (subscriber, #36192)
Parent article: OSDL to fund a kernel tech writer

Whoever is going to take that job should have as his 1st priority to add more examples to the linux kernel.IMHO this is one of the biggest problem of linux's docs,it lacks examples of coding drivers and core kernel components.The linux kernel books are not really better at that,except for the linux drivers book,but it goes too quickly out of date with the kernel!And this site too,that is the best site about Linux on the Net,should have code examples,real code examples,and not only updates of the kernel api and the kernel structure.

(Log in to post comments)

Examples? The whole thing is an example!

Posted Nov 9, 2006 6:56 UTC (Thu) by xoddam (subscriber, #2322) [Link]

> it lacks examples of coding drivers and core kernel components.

WTF? *Every* driver is an example driver!!!!

> this site too,that is the best site about Linux on the Net,
> should have code examples,real code examples,
> and not only updates of the kernel api and the kernel structure.

Really, the place for the example code is LKML. LWN is excellent at
linking to the relevant patches in the list archives.

It's Free Software dude, the whole thing is the example!

Examples? The whole thing is an example!

Posted Nov 9, 2006 16:47 UTC (Thu) by iabervon (subscriber, #722) [Link]

Actual drivers are notoriously full of things that seemed like a good idea when they were written, but we know better now, and things that weren't even good at the time, but nobody looked too closely. It would be useful to have *good* example drivers. (And, of course, a maintainer for them, because example drivers are even more likely to stick with out-of-date practices, since they don't get thoroughly tested and updated, due to not actually doing anything.)

Examples? The whole thing is an example!

Posted Nov 9, 2006 22:57 UTC (Thu) by k8to (subscriber, #15413) [Link]

I was about to make the point that example drivers are always even worse, and then you made it for me.

It would be great if somone was hard at working crafting and maintaining code and text designed to show people the ropes of kernel work, but that someone had better lean as heavily as possible on existing known-to-minimize errors techniques.

Examples? The whole thing is an example!

Posted Nov 10, 2006 1:13 UTC (Fri) by xoddam (subscriber, #2322) [Link]

The best we can possibly do in this department is to maintain working
code properly and update it to conform with best practice. As far as I'm
aware this is exactly the job that most kernel developers already do.

Sure, not every part of the kernel is up-to-the-minute. But I promise
you that code which is used by millions of people and looked after by
several responsive developers is in better shape than any dusty 'example'
on a website or in a book that doesn't push bits around for the general
public.

Examples? The whole thing is an example!

Posted Nov 10, 2006 20:19 UTC (Fri) by rgoates (subscriber, #3280) [Link]

How about designating specific drivers and other pieces of kernel code as examples worth emulating? Kernel hackers and driver writers can discuss/argue the merits and come to some decision about which pieces of code most deserve to be examples. I personally would greatly appreciate having such direction.

OSDL to fund a kernel tech writer

Posted Nov 9, 2006 15:54 UTC (Thu) by riel (subscriber, #3142) [Link]

There is some kernel documentation on the Kernel Newbies site, but if you have ideas for additional content I would be interested in hearing them.

Also, the content on the Kernel Newbies site is available under a creative commons license, and can be used as part of other documentation. The goal is to teach as many people as possible. If you have contributions to make, you can create yourself a login and help editing any time, since kernelnewbies.org is a wiki.

OSDL to fund a kernel tech writer

Posted Nov 10, 2006 18:38 UTC (Fri) by MisterIO (subscriber, #36192) [Link]

Yeah,I know there's kernelnewbies,there's kerneltrap,there was kerneltraffic,so why there's a Documentation folder in the Linux tree?Take it away if it's so useless there!And production code isn't good example code.Example code should be placed in the same folder where there are the documents for the same argument and it should be a focused peace of code,not too small and not too long.And it could be helpful here too!I can't even see why don't you want it?How could it be a problem to have good focused example code in he kernel?And don't tell that you started programming looking at the source code of something like glibc.Everyone starts with something like printf("Hello, world"); and then takes the next step looking at something more complex.The kernel is a really complex peace of code;you can't say : look at it and then start coding.Well you can,but that won't be a good help for newbies and kerneljanitors is not really better.It's mostly a way for kernel developers to leave to others the boring work!Anyway maybe I'm wrong,but this is what I think!

OSDL to fund a kernel tech writer

Posted Nov 12, 2006 15:27 UTC (Sun) by Blaisorblade (guest, #25465) [Link]

> The linux kernel books are not really better at that,except for the
> linux drivers book,but it goes too quickly out of date with the kernel!

I've had problems even at using a Linux driver book, namely Linux Device Drivers. Maybe I'm off topic since this is too detailed, but I couldn't explain myself without examples - I would have needed much more time to write this post).

I was not trying to write a driver from scratch, but to remove excess locking (which was doing harm) from an existing driver (arch/um/drivers/net_kern.c: uml_net_open in 2.6.18 is one offending place, with
spin_lock(&lp->lock);
...
um_request_irq(...) /* a request_irq wrapper, allocates memory with GFP_KERNEL*/
...
spin_unlock(&lp->lock);
).

In LDD3 examples there is no lock protecting against multiple concurrent open and/or close operations, which is correct, but there is also no explaination of why it is not needed (there is a complex *undocumented* state machine infrastructure preventing this) - and I've verified that in practice this error happens to other driver authors (in out-of-tree code).

Additionally, the code had to use a spinlock in _open to protect against concurrent ->read and ->write operations (again, not needed for the same reason) - which meant that sleep-inside-spinlock warnings were extremely common.

So, actual bugs were resulting from a lack of documentation.