Date: Sun, 24 Sep 2006 14:42:03 -0300 From: Duane Whitty <duane@dwlabs.ca> To: Marc Fonvieille <blackend@freebsd.org> Cc: freebsd-doc@freebsd.org Subject: Re: man pages and handbooks Message-ID: <4516C36B.7030701@dwlabs.ca> In-Reply-To: <20060924070721.GA961@gothic.blackend.org> References: <20060905223444.GA33935@dwpc.dwlabs.ca> <20060924070721.GA961@gothic.blackend.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Marc Fonvieille wrote:
> On Tue, Sep 05, 2006 at 07:34:44PM -0300, Duane Whitty wrote:
>> I've been spending a lot of time recently reading how SMP works, kernel
>> threads, SA/KSE, callouts, the differences between SCHED_4BSD and SCHED_ULE,
>> locking, caches, etc. I've still got a lot to learn and a lot to actually
>> start trying to apply in code.
>>
>> I've often thought this might be easier if some of the great material
>> available in the man pages was perhaps streamlined into the evolving
>> FreeBSD Architecture Handbook. This is just my opinion of course and
>> those of you with more experience than me may have good reasons for
>> not doing so.
>>
>> Barring any objections from the community in general and the DOC
>> project comitters in particular I would like to volunteer to
>> start adding some material from the man pages into the
>> FreeBSD Architecture Handbook. My first targets would be integrating
>> the material on mutex(9), mtx_*(9), pthread_*(9), lock*(9), atomic_*(9),
>> sched_4bsd(4), and sched_ule(4) into the material already present in the
>> handbook. I would also like to try my hand at creating diagrams to illustrate
>> the data structures used in our kernel code. Obviously as I learn more
>> I will probably find more material which would be interesting to have
>> integrated as well.
>>
> [...]
Hi,
First let me say thanks for your interest and feedback.
Input from experienced people such as yourself is very,
very appreciated.
I'm CCing docs@ so that the other interested or potentially
interested parties can stay involved.
>
> If you want to just merge/copy some manual pages parts in the
> arch-handbook then you miss the point since there's no gain in
> duplicating the information. For example if you want to talk about the
> ULE schedule we are not looking for a sched_ule(4) manual page copy but
> a documented text covering the features, how to use it or code with it,
I agree.
> etc.; another example would be the USB devices, if your look at the
> current chapter, the text explain how the USB stack works (it's quite
> the case) but miss a part explaining how to write a simple USB (HID?)
> driver.
I somewhat agree but I also don't believe that the
Architecture Handbook is the best location for detailed
tutorial information on how to develop for a specific
subsystem; Just my opinion. Is that not be what the
Developers' Handbook is for? [Not meant as a rhetorical
question]
To sum up, most of time, beside the outdated info, the book
> miss the detailed information on the layout/features of a subject and
> the application (driver, etc.) examples, i.e, what need a vanilla C
> coder to write/port something To FreeBSD.
>
> Marc
I guess my understanding of the FreeBSD Architecture
Handbook is that it tries to answer the questions
a) What does a particular subsystem do?
b) How are the goals of this subsystem accomplished
i.e., what are its data structures, what are its
algorithms?
c) Why does the subsystem use the data structures and
algorithms that it does? What are the trade-offs with
alternative methods and perhaps even the Handbook should
discuss past methods which did not work and why.
Best Regards,
Duane Whitty
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?4516C36B.7030701>