Date: Sun, 29 Aug 2004 15:08:33 -0400 From: Mathew Kanner <mat@cnd.mcgill.ca> To: Ruslan Ermilov <ru@freebsd.org> Cc: current@freebsd.org Subject: Re: [PATCH] sound(4) related manpages 5.3 TODO item Message-ID: <20040829190833.GA9796@cnd.mcgill.ca> In-Reply-To: <20040828142503.GA52613@ip.net.ua> References: <20040828142503.GA52613@ip.net.ua>
next in thread | previous in thread | raw e-mail | index | archive | help
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/
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040829190833.GA9796>