From owner-freebsd-current@FreeBSD.ORG Tue Dec 12 01:42:34 2006 Return-Path: X-Original-To: current@freebsd.org Delivered-To: freebsd-current@FreeBSD.ORG Received: from mx1.FreeBSD.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id C906416A54F for ; Tue, 12 Dec 2006 01:42:34 +0000 (UTC) (envelope-from imp@bsdimp.com) Received: from harmony.bsdimp.com (vc4-2-0-87.dsl.netrack.net [199.45.160.85]) by mx1.FreeBSD.org (Postfix) with ESMTP id 1206A44123 for ; Tue, 12 Dec 2006 01:32:32 +0000 (GMT) (envelope-from imp@bsdimp.com) Received: from localhost (localhost [127.0.0.1]) by harmony.bsdimp.com (8.13.4/8.13.4) with ESMTP id kBC1WeiH001249; Mon, 11 Dec 2006 18:32:41 -0700 (MST) (envelope-from imp@bsdimp.com) Date: Mon, 11 Dec 2006 18:33:38 -0700 (MST) Message-Id: <20061211.183338.1120057412.imp@bsdimp.com> To: scottl@samsco.org From: "M. Warner Losh" In-Reply-To: <457E034A.7080103@samsco.org> References: <20061210.231137.-1749707382.imp@bsdimp.com> <20061212005753.GJ86517@alchemy.franken.de> <457E034A.7080103@samsco.org> X-Mailer: Mew version 4.2 on Emacs 21.3 / Mule 5.0 (SAKAKI) Mime-Version: 1.0 Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-2.0 (harmony.bsdimp.com [127.0.0.1]); Mon, 11 Dec 2006 18:32:41 -0700 (MST) Cc: current@freebsd.org, nick@van-laarhoven.org Subject: Re: mk48txx X-BeenThere: freebsd-current@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Discussions about the use of FreeBSD-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 12 Dec 2006 01:42:34 -0000 In message: <457E034A.7080103@samsco.org> Scott Long writes: : Marius Strobl wrote: : > On Sun, Dec 10, 2006 at 11:11:37PM -0700, M. Warner Losh wrote: : >> In message: <20061209210629.GG86517@alchemy.franken.de> : >> Marius Strobl writes: : >> : : >> : I favor having no man page over having something incomplete : >> : or inadequate like f.e. esp.4 or bus_space.9 as IMO wrong : >> : information can confuse way more and leaves a worse impression : >> : than no information at all. : >> : >> bus_space.9 isn't incomplete. The problem is that it is too complete : >> and general, if anything. It is hard to penetrate. : > : > I mentioned bus_space.9 as an example of a man page that I'd : > describe as inadequate; both the sections about mapping and : > unmapping as well as allocating and freeing bus space are : > still verbatim from the NetBSD rev. 1.9 one AFAICT, which : > describes concepts in these sections that don't really apply : > to FreeBSD. Granted, on some platforms like FreeBSD/i386 : > one can probably succeed in doing actual reads and writes : > by only using the functions mentioned in bus_space.9, but : > it totally fails to give the slightest hint (not even a .Xr) : > on how to obtain the bus space tag and handle the right way : > in FreeBSD, so it will actually work on all platforms, which : > is the whole point of the bus_space interface. The current : > bus_space.9 actually tells that some of its sections "may or : > may not apply to the FreeBSD version" and "many parts of the : > interface are unspecified", but that's essentially telling : > the user that she/he has to figure it out herself/himself, : > which IMO defeats the purpose of having a man page in the : > first place. : > : > Marius : > : : Hate to say it, but these things don't fix themselves. If you're hoping : to shame Warner into fixing it, I think that his free time is quite : spoken for. Mine is too, though I'd be happy to review corrections to : it for technical and grammar correctness. I'm happy to review things as well. I have very little free time these days due to the baby, the merger, and the mad rush to get product out ASAP. I think you overgeneralize about the defects in bus_space. It tells you the basics so you can figure it out yourself. Could it be better? Sure. Is it better than nothing like we had before? Absolutely. Warner