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

[Mathew Kanner]

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/