From owner-freebsd-doc@FreeBSD.ORG Sat Sep 23 21:15:31 2006 Return-Path: X-Original-To: Freebsd-doc@freebsd.org Delivered-To: Freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 5080116A403; Sat, 23 Sep 2006 21:15:31 +0000 (UTC) (envelope-from duane@dwlabs.ca) Received: from smtpout.eastlink.ca (smtpout.eastlink.ca [24.222.0.30]) by mx1.FreeBSD.org (Postfix) with ESMTP id 7FC5D43D45; Sat, 23 Sep 2006 21:15:27 +0000 (GMT) (envelope-from duane@dwlabs.ca) Received: from ip04.eastlink.ca ([24.222.10.20]) by mta01.eastlink.ca (Sun Java System Messaging Server 6.2-4.03 (built Sep 22 2005)) with ESMTP id <0J6200FCLDLIQW00@mta01.eastlink.ca>; Sat, 23 Sep 2006 18:12:54 -0300 (ADT) Received: from blk-224-199-230.eastlink.ca (HELO [192.168.0.103]) ([24.224.199.230]) by ip04.eastlink.ca with ESMTP; Sat, 23 Sep 2006 18:15:26 -0300 Date: Sat, 23 Sep 2006 18:15:01 -0300 From: Duane Whitty In-reply-to: <1159024900.674.15.camel@localhost> To: Joel Dahl Message-id: <4515A3D5.4010003@dwlabs.ca> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AQAAAHZAFUUNi2I X-IronPort-AV: i="4.09,208,1157338800"; d="scan'208"; a="810551053:sNHT26282960" References: <3c3d11cf0609130258s5ebf8274q18acf31a83b403a7@mail.gmail.com> <1158144023.670.36.camel@localhost> <450B42FD.7070508@dwlabs.ca> <3c3d11cf0609180443y45d1e3d9p8d3993588cdc89c2@mail.gmail.com> <1159024900.674.15.camel@localhost> User-Agent: Thunderbird 1.5.0.4 (X11/20060617) Cc: Paul Wilson , Freebsd-doc@FreeBSD.org Subject: Re: man pages and handbooks X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 23 Sep 2006 21:15:31 -0000 Joel Dahl wrote: > On Mon, 2006-09-18 at 12:43 +0100, Paul Wilson wrote: >> On 16/09/06, Duane Whitty 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