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

[ Please keep me Cc:ed when replying ]

On Mon, Aug 30, 2004 at 04:28:52PM +0100, cg wrote:
> On Sun, 29 Aug 2004 23:59:42 +0300, Ruslan Ermilov <ru_at_FreeBSD.org> wrote:
> 
> >I wish there would be more consistency in naming.  Previously,
> >we had the csa(4) manpage, "device csa", and /dev/csa* entries.
> >Now we will have the snd_csa(4) manpage, "device snd_csa", but
> >still /dev/csaX entry.
> >
> >Also, in the old world, "midi" devices were created as children
> >of "pcm" devices, so "hint.pcm.0" hints for non-PnP ISA devices
> >looked correct.  In new world with your updated midi(4), what
> >will be the hints for the ISA device that implements PCM and
> >MIDI?  hint.pcm.0 and hint.midi.0?
> 
> the intention behind the renaming was to simplify the naming scheme, and  
> to glue pcm and midi together such that card drivers didn't have to  
> separate out their pcm, midi and independant code.
> 
> if you look at any of the current card drivers, you'll find that they make  
> several calls into the pcm code.  those supporting midi, likewise, call  
> into midi code.  having midi and pcm as seperate devices gives the  
> impression that they're independant, but if we allowed that to be the case  
> the drivers would have to become far more complex.  ie, they each would  
> require a separate module for their pcm, midi and general parts because if  
> say, only midi was compiled into the kernel then the pcm code in the  
> drivers would fail to link.  likewise, drivers supporting midi would fail  
> to link if only pcm was present.
> 
> for modules, this problem can be solved with dependancies, but the only  
> solution for a static kernel would be to declare that if you wish to  
> compile a driver that supports pac and midi, both device pcm and device  
> midi must be specified.
> 
> rather than leave the situation that way, we elected to combine the pcm  
> and midi devices into one, so the card drivers could assume both were  
> present.
> 
> renaming the card modules is a different story, and although i was in  
> favour of it, i now feel it wasn't such a good idea in its current form.   
> because pcm is just a framework rather than an actual device from the  
> kernel's point of view, the driver name would show up in dmesg etc as  
> snd_emu10k1 or whatever.  while that in itself wouldn't cause a problem,  
> it would result in each driver using a different devclass - and there are  
> some fairly fundamental assumptions in the pcm code that is designed  
> around being able to translate a unit number to a device_t.
> 
> if the drivers were changed to register as snd_* rather than pcm, but  
> remain sharing their devclass, there would be interesting results: either  
> all sound devices would show up with the name of the one that attached  
> first (eg an ich and emu10k1 as snd_ich0 and snd_ich1) or the unit numbers  
> would be shared across devices (eg, snd_ich0, snd_maestro1, snd_cmi2...)
> 
> both of those possible outcomes would be worse than the current situation,  
> in my opinion.
> 
> what we can - and should - do is rename the "pcm" devclass to "sound".   
> this would make sound devices show up as sound0 etc, and make the  
> hints/sysctls be hw.sound0.*.  we also need to make sure that the sound.ko  
> module contains both pcm and midi.
> 
I agree that renaming the "pcm" devclass to "snd" or "sound" is a good
idea, and I like the "snd" more for a couple of reasons (please see
below).  Let me now check if I got you right.  Assuming it will be
renamed to "snd", what about the /dev entries, will they be still
/dev/pcm{unit}, /dev/mixer{unit}, and /dev/midi{unit}?  If, for example,
I have two sound cards installed, first without MIDI, and second with
MIDI, what will I have in /dev?  pcm0, mixer0, *no* midi0, pcm1, mixer1,
and midi1?  And these devices ("pcm", "mixer", and "midi") will be all
children of the "snd" device.  And for the ISA sound card with MIDI
support, the following device hints and corresponding /dev entries?

     hint.snd.0.at="isa"
     hint.snd.0.irq="5"
     hint.snd.0.drq="1"
     hint.snd.0.flags="0x0"
     /dev/pcm0
     /dev/mixer0
     /dev/midi0

> it might be nice to have a meta device called sound_all which pulled in  
> all the drivers plus the pcm and midi code, and a corresponding kld.
> 
The snd_driver.ko module already provides this feature.  Should we need
such a "config(8) device" is another question.  I don't personally see
a fit in it -- the GENERIC kernel can already have all snd_* devices
and the generic "snd" device.

> i wonder if we still have the opportunity to rename snd* to sound*?  or  
> possibly sound to snd which would mesh better with /dev/sndstat.
> 
Yes, please, the latter.  ;)

So, to summarize, I'd have liked to see the following happen:

- "snd" is the generic sound device (module snd.ko)
- "snd_foo" is the sound driver for foo (module snd_foo.ko)
- "pcm" devclass renamed to "snd"
- "pcm", "mixer", and "midi" devices are created as children of "snd"
- ISA device hints become snd.<unit>.{at,irq,drq,flags,...}
- the hw.snd. sysctl tree stays unmodified, including the following
  convention: PCM-related sysctls will have the hw.snd.pcm<unit>
  prefix, and MIDI-related sysctls (should there be any) will have the
  hw.snd.midi<unit> prefix.

And one final question: if the plan is as described here, it probably
makes sense to do it now, before 5.3, or postpone the "manpage and
handbook" sound related TODO items until it's actually done and merged
into RELENG_5.  I'd like to avoid repo-copying the pcm(4) manpage to
sound(4) now, only to repo-copy it later to snd(4).  If this doesn't
happen in time for 5.3, I suggest the following emergency plan for
now:

- repo-copy (and tweak as necessary) all bridge drivers manpages,
  as shown in my patch;

- do *not* repo-copy pcm(4) to sound(4) yet, just link it, possibly
  mentioning in the manpage that the generic driver will soon be
  renamed from "sound" to "snd",

- fix hints in NOTES (as in my patch) to match reality.

When "sound" -> "snd" conversion is actually done, repo-copy
pcm(4) to sound(4), tweak as necessary, documenting what the
"sound" device really is, mentioning "pcm", "mixer", and "midi"
sub-devices, link sound(4) to pcm(4), mixer(4), and midi(4).

Please let me know how to proceed...


Cheers,
-- 
Ruslan Ermilov
ru_at_FreeBSD.org
FreeBSD committer