man pages and handbooks

[Duane Whitty]

Joel Dahl wrote:
> On Mon, 2006-09-18 at 12:43 +0100, Paul Wilson wrote:
>> On 16/09/06, Duane Whitty <duane at dwlabs.ca> wrote:
>>         I intend to work on this one way or another.  Hopefully it
>>         will happen in a way that makes it readily available to the
>>         wider FreeBSD developer community.  I can host a server and
>>         docs if necessary but it sounds like the Perforce repo 
>>         already running would be ideal.  I'll have to install the
>>         client and come up to speed on using it but I don't
>>         anticipate it being a problem.
>>
>> What's the next move then? I'm eager to get the ball rolling :) 
> 
> Sorry for the delay[*].
> 
> I've discussed this briefly with a couple of doc committers and we're a
> bit unsure about how to proceed.  My suggestion is that you (Paul and
> Duane) do something like this:
> 
> 1.  Start out by defining what areas you would like to work on, this way
> it'll be easier for us to know what we can expect.
> 
> 2.  Work together in some way, and keep your work synchronized.
> 
> 3.  Submit patches to doc@, and CC hackers@ or arch@ (but not both!) if
> you need some clever kernel hacker to review your work.  Try to send
> small incremental patches, since it will be a lot easier for us to
> review and commit them that way.  PR's may also be a good idea.
> 
> If all this becomes a major PITA to handle, maybe we can discuss setting
> up p4 accounts etc.  I'm very interested in getting the ball rolling,
> but I'd like to see some results (patches etc) before someone sets you
> up with p4 accounts.  You would do the project a big favor if you are
> able to finish this project, and I am very much looking forward to start
> reviewing your patches.  The Arch handbook has been lacking in content
> for far too long now.
> 
> [*] /me kicks everyone in CVSROOT-doc/access.  Am I the only interested
> in docs these days?  What could possibly be more interesting then doc
> discussions?  ;-)
> 
Hi,

What I would like to propose then is that we make 7.X our 
target.  If I were already a kernel architecture expert I 
might contemplate documenting two similar but different 
architectures but, as I am not, I would prefer to 
concentrate on the CURRENT kernel and its subsystems.

My main interests include locking, threads, and scheduling. 
  I'm not sure what to work on first; I need to cover 
mutex(9) and mtx_*[39] and the lockmgr(9) functions.  Also I 
need to cover atomic variables and operations, why they are 
needed and when they are used.

I also want to cover kernel organization, the distinction 
between threads and processes, scheduling of threads and 
processes, the idea of kernel preemption, kernel threads, 
user-land threads, and 1:1 threading versus M:N threading.

I would also like to learn about and discuss the issue of 
whether one kernel architecture can do it all.  Some of the 
issues effecting UP and UP small scale multi-core machines 
are probably different than the issues effecting 
multiprocessor multi-core massively threaded architectures. 
  What are those issues and what type of kernel would best 
support each architecture or can one kernel do it all.

The great thing is that most of this has been written 
already by others.  It just needs, mostly, to be brought 
into one place.

Best Regards,

Duane Whitty