From owner-freebsd-current@FreeBSD.ORG Tue Dec 12 01:01:27 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 7E87016A416 for ; Tue, 12 Dec 2006 01:01:27 +0000 (UTC) (envelope-from marius@alchemy.franken.de) Received: from alchemy.franken.de (alchemy.franken.de [194.94.249.214]) by mx1.FreeBSD.org (Postfix) with ESMTP id 489A543CCF for ; Tue, 12 Dec 2006 00:56:38 +0000 (GMT) (envelope-from marius@alchemy.franken.de) Received: from alchemy.franken.de (localhost [127.0.0.1]) by alchemy.franken.de (8.13.8/8.13.8/ALCHEMY.FRANKEN.DE) with ESMTP id kBC0vr7l068059; Tue, 12 Dec 2006 01:57:53 +0100 (CET) (envelope-from marius@alchemy.franken.de) Received: (from marius@localhost) by alchemy.franken.de (8.13.8/8.13.8/Submit) id kBC0vr2h068058; Tue, 12 Dec 2006 01:57:53 +0100 (CET) (envelope-from marius) Date: Tue, 12 Dec 2006 01:57:53 +0100 From: Marius Strobl To: "M. Warner Losh" Message-ID: <20061212005753.GJ86517@alchemy.franken.de> References: <20061209185539.GA34399@alchemy.franken.de> <20061209201438.B42195@localhost> <20061209210629.GG86517@alchemy.franken.de> <20061210.231137.-1749707382.imp@bsdimp.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20061210.231137.-1749707382.imp@bsdimp.com> User-Agent: Mutt/1.4.2.2i Cc: nick@van-laarhoven.org, current@freebsd.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:01:27 -0000 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