[src/trunk]: src/share/man/man4 Update audio man page with regard to audio ch...

[nat <nat%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/28af1a38ed8f
branches:  trunk
changeset: 349497:28af1a38ed8f
user:      nat <nat%NetBSD.org@localhost>
date:      Mon Dec 12 11:49:27 2016 +0000

description:
Update audio man page with regard to audio changes.
OK wiz@

diffstat:

 share/man/man4/audio.4 |  95 +++++++++++++++++++++++++++++++++++++++++++------
 1 files changed, 82 insertions(+), 13 deletions(-)

diffs (150 lines):

diff -r 774a27dcbdfe -r 28af1a38ed8f share/man/man4/audio.4
--- a/share/man/man4/audio.4    Mon Dec 12 10:46:39 2016 +0000
+++ b/share/man/man4/audio.4    Mon Dec 12 11:49:27 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: audio.4,v 1.72 2011/09/06 01:17:48 jmcneill Exp $
+.\"    $NetBSD: audio.4,v 1.73 2016/12/12 11:49:27 nat Exp $
 .\"
 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd September 5, 2011
+.Dd December 11, 2016
 .Dt AUDIO 4
 .Os
 .Sh NAME
@@ -67,11 +67,16 @@
 .Pa /dev/sound ,
 but no other operations.
 .Pp
-In contrast to
 .Pa /dev/sound
-which has the exclusive open property
+and
+.Pa /dev/audio
+can be opened at
+.Em any
+time and audio sources of different precision and playback
+parameters i.e frequency will be mixed and played back simultaneously.
+.Pp
 .Pa /dev/audioctl
-can be opened at any time and can be used to manipulate the audio device
+can be used to manipulate the audio device
 while it is in use.
 .Sh SAMPLING DEVICES
 When
@@ -84,16 +89,67 @@
 When
 .Pa /dev/sound
 is opened, it maintains the previous audio sample mode and
-record/playback mode.
+record/playback mode most recently set on
+.Pa /dev/sound
+by any open channel.
 In all other respects
 .Pa /dev/audio
 and
 .Pa /dev/sound
 are identical.
+.Sh VIRTUAL CHANNELS
+Any process may open a sampling device at a given time.
+There is a constraint of
+.Em one
+device per process and file descriptors may
+.Em not
+be shared between processes.
 .Pp
-Only one process may hold open a sampling device at a given time
-(although file descriptors may be shared between processes once the
-first open completes).
+Virtual channels are converted to a common format, signed linear encoding,
+frequency channels and precision.
+These can be modified to taste by the following
+.Xr sysctl 8
+variables.
+.Pp
+.Bl -tag -width -compact
+.It hw.driverN.precision
+.It hw.driverN.frequency
+.It hw.driverN.channels
+.It hw.driverN.saturate
+.El
+.Pp
+Where
+.Em driverN
+corresponds to the underlying audio device driver and device number.
+e.g In the case of an hdafg supported device the variables would be:
+hw.hdafg0.channels, hw.hdafg0.precision, hw.hdafg0.frequency.
+.Pp
+For best results, values close to the underlying hardware should be chosen.
+These variables may only be changed when the sampling device is not in use.
+.Pp
+An additional
+.Xr sysctl 8
+variable controls how the samples are combined, hw.driverN.saturate.
+.Pp
+By default it is set to true.
+This means that volumes are not adjusted for each channel to be mixed.
+All virtual channels will use the
+.Em maximum
+set master volume unless the virtual channel volume is lowered by the user.
+.Pp
+If set to false the channels are
+.Em divided
+evenly in volume with respect to the master volume.
+.Pp
+Each virtual channel has a corresponding mixer:
+.Bl -tag -width -compact
+.It outputs.dacN  Output volume
+.It inputs.micN   Recording volume
+.El
+.Pp
+Where N is the virtual channel number.
+e.g ouputs.dac0 controlling playback volume and outputs.mic0 controlling
+recording volume for the first virtual channel.
 .Pp
 On a half-duplex device, writes while recording is in progress will be
 immediately discarded.
@@ -177,6 +233,17 @@
 commands are supported on the sample devices:
 .Pp
 .Bl -tag -width indent
+.It Dv AUDIO_SETPROC (struct audio_pid)
+This command will select the audio device opened by pid.
+.Bd -literal
+struct audio_pid {
+        pid_t   pid;
+        lwpid_t lwpid;
+};
+.Ed
+.Pp
+Currently the lpwid value is
+.Em ignored .
 .It Dv AUDIO_FLUSH
 This command stops all playback and recording, clears all queued
 buffers, resets error counters, and restarts recording and playback as
@@ -682,7 +749,8 @@
 .Xr ioctl 2 ,
 .Xr ossaudio 3 ,
 .Xr midi 4 ,
-.Xr radio 4
+.Xr radio 4 ,
+.Xr sysctl 8
 .Ss ISA bus
 .Xr aria 4 ,
 .Xr ess 4 ,
@@ -716,7 +784,8 @@
 .Ss USB
 .Xr uaudio 4
 .Sh BUGS
-If the device is used in
 .Xr mmap 2
-it is currently always mapped for writing (playing) due to
-VM system weirdness.
+currently does not work and should be avoided.
+.Sh HISTORY
+Support for virtual channels and mixing first appeared in
+.Nx 8.0 .