[PATCH] sound(4) related manpages 5.3 TODO item

Mathew Kanner mat at cnd.mcgill.ca
Sun Aug 29 12:01:29 PDT 2004

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


> 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.

		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/

More information about the freebsd-current mailing list