From owner-freebsd-current@FreeBSD.ORG Sun Aug 29 19:01:28 2004 Return-Path: Delivered-To: freebsd-current@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id D541216A4DC; Sun, 29 Aug 2004 19:01:20 +0000 (GMT) Received: from hak.cnd.mcgill.ca (hak.cnd.McGill.CA [132.216.11.133]) by mx1.FreeBSD.org (Postfix) with ESMTP id 7072D43D4C; Sun, 29 Aug 2004 19:01:20 +0000 (GMT) (envelope-from mat@hak.cnd.mcgill.ca) Received: from hak.cnd.mcgill.ca (localhost [127.0.0.1]) by hak.cnd.mcgill.ca (8.12.9/8.12.8) with ESMTP id i7TJ8X1M011556; Sun, 29 Aug 2004 15:08:33 -0400 (EDT) (envelope-from mat@hak.cnd.mcgill.ca) Received: (from mat@localhost) by hak.cnd.mcgill.ca (8.12.9/8.12.8/Submit) id i7TJ8X5P011555; Sun, 29 Aug 2004 15:08:33 -0400 (EDT) Date: Sun, 29 Aug 2004 15:08:33 -0400 From: Mathew Kanner To: Ruslan Ermilov Message-ID: <20040829190833.GA9796@cnd.mcgill.ca> References: <20040828142503.GA52613@ip.net.ua> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20040828142503.GA52613@ip.net.ua> User-Agent: Mutt/1.4.1i Organization: I speak for myself, operating in Montreal, CANADA X-Spam-Status: No, hits=0.0 required=5.0 tests=none autolearn=no version=2.62 X-Spam-Checker-Version: SpamAssassin 2.62 (2004-01-11) on hak.cnd.mcgill.ca cc: Cameron Grant cc: multimedia@freebsd.org cc: "Simon L. Nielsen" cc: Seigo Tanimura cc: current@freebsd.org Subject: Re: [PATCH] sound(4) related manpages 5.3 TODO item X-BeenThere: freebsd-current@freebsd.org X-Mailman-Version: 2.1.1 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: Sun, 29 Aug 2004 19:01:29 -0000 On Aug 28, Ruslan Ermilov wrote: Hello Ruslan, > One and most important thing I'm not sure I understand, and > that's causing a lot of confusion, is why "device pcm" was > renamed to "device sound" in the first place? I believe the > reason is that "device sound" is a generic sound driver, > which has support for PCM playback, mixer, /dev/sndstat, > eventually MIDI, sequencer, and so on. Individual sound > drivers are free to implement either of these interfaces. > Most of them implement "pcm" nowadays, so saying that > "pcm was renamed to sound" is not quite correct. In other > words, the sound.ko module provides the infrastructure for > more than just PCM, and the sound(4) manpage should eventually > document more than just PCM. Does that sound correct? Sounds correct on all accounts. Also, the synopsis should indicate that the preferred method to load sound is to set sound_load="YES" in loader.conf and barely mention kernel options, and otherwise ignore ISA and PNP. > Also, there seems to be some confusion between the modules, > drivers, and devices that they implement, which are different > beasties, and are often named differently, and this causes > some misunderstandings and bugs (see below). Note that sndstat now lists the kld name (if loaded as such) in the device listings. > > Anyway, the attached patch adopts the sound(4) related man > pages to the new world order. How to proceed: > > 1. The following repo-copies in /home/ncvs/src/share/man/man4 > should be made (there were made locally to produce the > patch): > > pcm.4,v -> sound.4,v > csa.4,v -> snd_csa.4,v > gusc.4,v -> snd_gusc.4,v > maestro3.4,v -> snd_maestro3.4,v > sbc.4,v -> snd_sbc.4,v > uaudio.4,v -> snd_uaudio.4,v Good. > > 2. The old manpages (on the left) were removed, and aren't > included in the patch. > > 3. After repo-copies and deletes, the attached patch should be > applied. It's mostly mechanical (foo -> snd_foo, pcm -> sound), > with the following notable exceptions: > > - Note that non-PnP ISA cards, such as those handled by snd_mss(4) > and snd_ad1816(4), still require hints of the form > > hint.pcm.0.at="isa" > hint.pcm.0.irq="5" > hint.pcm.0.drq="1" > hint.pcm.0.flags="0x0" > > because they implement device "pcm". Granted, the difference > between module and driver name is confusing enough that Seigo > misspelled hints names in sys/conf/NOTES, and Simon misspelled > them in the new snd_ad1816(4) manpage. The patch corrects the > hints names in the snd_ad1816(4) manpage and NOTES. The patch > removes the "hint.snd_mss" from NOTES because (like was said) > the snd_mss(4) module implements the "pcm" device, hence the > hints start with "hint.pcm", and this is already documented > in the sound(4) manpage. Module snd_sbc(4) and snd_gusc(4) > are special in that they implement PCM support through the > bridge device ("sbc" and "gusc", respectively), with "pcm" > device as a child. For them, ISA hints should be spelled > "hint.sbc" and "hint.gusc", respectively. This is also fixed > in NOTES. This is a very good catch, I never noticed this. > > - The patch also fixes the SYNOPSIS section of the snd_maestro3(4) > manpage to align it with other sound drivers manpages, and adds > missing "device sound" to almost all of the snd_*(4) manpages. Yes please. > > Does that look sane? I'd be grateful is someone more fluent with > our sound subsystem could review this. I've read the diff and it all looks very good to me, thank you very much for taking this on. --Mat -- Applicants must also have extensive knowledge of UNIX, although they should have sufficiently good programming taste to not consider this an achievement. - MIT AI Lab job ad in the /Boston Globe/