Module Name:	src
Committed By:	fredb
Date:		Sat Jan 31 00:07:56 UTC 2004

Modified Files:
	src/share/man/man4: audio.4
	src/share/man/man9: audio.9
	src/sys/dev: audio.c audiovar.h

Log Message:
Fix a couple of long-standing bugs in the volume control(s) part of the
audio device interface:

1) When attempting to match the appropriate mixer control, we weren't
checking the class label, but only the second level label, so for
devices that had both an "inputs.cd" and a "record.cd", for example,
we could never do the right thing except by chance. For this reason,
evidently, all the record masters were labeled (by the underlying
drivers) either "record.record" or "record.volume", to distinguish
from "outputs.master". We'll now accept "record.master", and document
that as the the new preferred way.

2) More importantly, the model was deficient. Selecting a port on many
chips completely disables most of the level controls, which doesn't play
nice with other applications which are trying to use the interface. Now,
selecting a port simply sets which mixer input control shall be changed,
setting state in the audio layer. In other words, the "mixerout" port
is really selected all the time, enabling the final stage mixer, and
setting "gain" sets the level of the appropriate input. It should be
possible for separate applications to each control the mic, dac, and cd
inputs at the same time using this interface, simply by reiterating their
port selections with each change, but applications that don't bother to
do that aren't any worse off than they were before.

The user is expected to set the master output with another application,
dedicated to that task. Though it is now meaningful to select "no port"
with the audio device interface, to manipulate the master output, there's
no particular reason for an audio device consumer to do that. (I added
the capability in order to restore the initial state of the audio device,
for testing purposes. It might also be useful to users of broken binary-
only applications.)

Observe that the mixer device interface (and so, "mixerctl") still
retains all capabilities, including the ability to set the actual input
port on the chip, overriding the level controls. No change is being made
to the mixer device interface. The mixer device simply presents all the
controls on the chip, with no attempt at abstraction, so there are no
bugs there.

The upshot is, that applications that have been trying to use the audio
device interface to change the volume, such as mplayer, now "just work".

I've tested these changes extensively with "eso" and "eap" since first
proposing them on tech-kern last January, and somewhat with "esm" and a
few others. This closes both PR kern/10221, and PR kern/17159.


To generate a diff of this commit:
cvs rdiff -r1.56 -r1.57 src/share/man/man4/audio.4
cvs rdiff -r1.25 -r1.26 src/share/man/man9/audio.9
cvs rdiff -r1.181 -r1.182 src/sys/dev/audio.c
cvs rdiff -r1.29 -r1.30 src/sys/dev/audiovar.h

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.