On Tue, 11 Feb 2003, Frederick Bruckman wrote:

> While investigating a fix for PR's kern/10221 and kern/17159
> (basically, audioctl -w play.gain doesn't work),...

Well, I've gotten some encouragement, but no technical review.
Possibly the details just aren't that interesting! Follows are the
changes to the man pages, to give one more chance to comment, before
I commit. [*] Most of what's below actually reflects the current state
of affairs. The only user-visible change is that the recording master
will be called "record.master", now that the bug that required
second-level labels to be unique is (or will soon be) fixed.

[*] Please check the archives for the (proposed) changes to audio.c
and audiovar.h. Those patches are against current, but they will apply
to, and compile against, 1.6_STABLE and _RC*.

Index: man4/audio.4
===================================================================
RCS file: /cvsroot/src/share/man/man4/audio.4,v
retrieving revision 1.50
diff -u -U5 -r1.50 audio.4
--- man4/audio.4	2002/03/13 00:55:02	1.50
+++ man4/audio.4	2003/02/18 17:09:09
@@ -589,21 +589,35 @@
 of the mask bits can be used.
 .Pp
 The
 .Va mixer_class
 field identifies what class of control this is.
-This value is set to the index value used to query the class itself.
-For example, a mixer level controlling the input gain on the
-.Dq line in
-circuit would be a class that matches an input class device
-with the name
+The
+.Pq arbitrary
+value set by the hardware driver may be determined by examining the
+.Va mixer_class
+field of the class itself,
+a mixer of type
+.Dv AUDIO_MIXER_CLASS .
+For example, a mixer controlling the input gain on the line in circuit
+would have a
+.Va mixer_class
+that matches an input class device with the name
 .Dq inputs
-.Dv ( AudioCinputs ) .
+.Dv ( AudioCinputs ) ,
+and would have a
+.Va label
+of
+.Dq line
+.Dv ( AudioNline ) .
 Mixer controls which control audio circuitry for a particular audio
 source (e.g. line-in, CD in, DAC output) are collected under the input class,
 while those which control all audio sources (e.g. master volume,
 equalization controls) are under the output class.
+Hardware devices capable of recording typically also have a record class,
+for controls that only affect recording,
+and also a monitor class.
 .Pp
 The
 .Va next
 and
 .Va prev
Index: man9/audio.9
===================================================================
RCS file: /cvsroot/src/share/man/man9/audio.9,v
retrieving revision 1.23
diff -u -U5 -r1.23 audio.9
--- man9/audio.9	2002/10/14 13:43:14	1.23
+++ man9/audio.9	2003/02/18 17:09:17
@@ -504,55 +504,86 @@
 .Pp
 The
 .Va query_devinfo
 method should define certain mixer controls for
 .Dv AUDIO_SETINFO
-to be able to change the port and gain.
+to be able to change the port and gain,
+and
+.Dv AUDIO_GETINFO
+to read them, as follows.
 .Pp
-If the audio hardware is capable of input from more
-than one source it should define
+If the record mixer is capable of input from more than one source,
+it should define
 .Dv AudioNsource
 in class
 .Dv AudioCrecord .
 This mixer control should be of type
 .Dv AUDIO_MIXER_ENUM
 or
 .Dv AUDIO_MIXER_SET
 and enumerate the possible input sources.
-For each of the named sources there should be
-a control in the
-.Dv AudioCinputs
+Each of the named sources for which the recording level can be set
+should have a control in the
+.Dv AudioCrecord
 class of type
-.Dv AUDIO_MIXER_VALUE
-if recording level of the source can be set.
-If the overall recording level can be changed (i.e., regardless
-of the input source) then this control should be named
-.Dv AudioNrecord
+.Dv AUDIO_MIXER_VALUE ,
+except the
+.Qq mixerout
+source is special,
+and will never have its own control.
+Its selection signifies,
+rather,
+that various sources in class
+.Dv AudioCrecord
+will be combined and presented to the single recording output,
+in the same fasion that the sources of class
+.Dv AudioCinputs are combined and presented to the playback output(s).
+If the overall recording level can be changed,
+regardless of the input source,
+then this control should be named
+.Dv AudioNmaster
 and be of class
-.Dv AudioCinputs .
+.Dv AudioCrecord .
+.Pp
+Controls for various sources that affect only the playback output,
+as opposed to recording,
+should be in the
+.Dv AudioCinputs class.
 .Pp
-If the audio hardware is capable of output to more than
-one destination it should define
-.Dv AudioNoutput
+If the play
+mixer is capable of output to more than one destination,
+it should define
+.Dv AudioNselect
 in class
-.Dv AudioCmonitor .
+.Dv AudioCoutputs .
 This mixer control should be of type
 .Dv AUDIO_MIXER_ENUM
 or
 .Dv AUDIO_MIXER_SET
 and enumerate the possible destinations.
-For each of the named destinations there should be
+For each of the named destinations for which the output level can be set,
+there should be
 a control in the
 .Dv AudioCoutputs
 class of type
-.Dv AUDIO_MIXER_VALUE
-if output level of the destination can be set.
-If the overall output level can be changed (i.e., regardless
-of the destination) then this control should be named
+.Dv AUDIO_MIXER_VALUE .
+If the overall output level can be changed,
+which is invariably the case,
+then this control should be named
 .Dv AudioNmaster
 and be of class
 .Dv AudioCoutputs .
+.Pp
+There's one additional source recognized specially by
+.Dv AUDIO_SETINFO
+and
+.Dv AUDIO_GETINFO ,
+to be presented as monitor_gain,
+and that is a control named
+.Dv AudioNmonitor ,
+of class
+.Dv AudioCmonitor .
 .Sh SEE ALSO
 .Xr audio 4
 .Sh HISTORY
 This
 .Nm


Frederick