Date: Sun, 24 Sep 2006 15:13:58 -0300 From: Duane Whitty <duane@dwlabs.ca> To: Marc Fonvieille <blackend@freebsd.org> Cc: Paul Wilson <paulalexwilson@gmail.com>, freebsd-doc@freebsd.org, Joel Dahl <joel@FreeBSD.org> Subject: Re: man pages and handbooks Message-ID: <4516CAE6.40601@dwlabs.ca> In-Reply-To: <4516C36B.7030701@dwlabs.ca> References: <20060905223444.GA33935@dwpc.dwlabs.ca> <20060924070721.GA961@gothic.blackend.org> <4516C36B.7030701@dwlabs.ca>
next in thread | previous in thread | raw e-mail | index | archive | help
Duane Whitty wrote: > 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. > May be the above should also include, in the same document, c.1) What doesn't work as well as we'd like it to in this subsystem? d) When and how should I use a particular subsystem e) Example code for using a particular subsystem f) Debugging methods specific to each subsystem Best Regards, Duane Whitty > Best Regards, > > Duane Whitty >
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?4516CAE6.40601>