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

On Sat, Aug 28, 2004 at 05:25:03PM +0300, Ruslan Ermilov wrote:
> Gang,
> 
> [ Please keep me Cc:ed when replying. ]
> 
> I've picked up the "sound(4) related manual pages" item from
> the 5.3-RELEASE TODO list.
> 
> While working on adopting the pcm(4) and related manpages to
> the new world order, I have noticed some odds that I'd like
> your comments on first, before I proceed further.
> 
> 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?
>

I'm not a sound(4) expert, but I think you're right.
However, I see something that may be confusing for the new comer: in the
kernel we add:

device sound
device snd_ich 		# as example

and in /dev/sndstat we see:

FreeBSD Audio Driver (newpcm)
Installed devices:
pcm0: <Intel ICH3 (82801CA)> at io 0xd800, 0xdc80 irq 5 bufsz 16384 kld
snd_ich (1p/2r/0v channels duplex default)

or in dmesg:

pcm0: <Intel ICH3 (82801CA)> port 0xdc80-0xdcbf,0xd800-0xd8ff irq 5 at
device 31.5 on pci0
pcm0: [GIANT-LOCKED]
pcm0: <Cirrus Logic CS4205 AC97 Codec>


Are the "pcm0" and "newpcm" words totally correct here, why no sound/snd ?

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

perfect!

> Does that look sane?  I'd be grateful is someone more fluent with
> our sound subsystem could review this.
> 

I'm not more fluent than you, but your changes seem correct.

Marc