Module Name: src
Committed By: martin
Date: Thu Jun 7 18:24:16 UTC 2018
Modified Files:
src/distrib/sets/lists/comp [netbsd-8]: mi
src/distrib/sets/lists/man [netbsd-8]: mi
src/share/man/man4 [netbsd-8]: audio.4
src/share/man/man7 [netbsd-8]: Makefile intro.7
src/share/man/man9 [netbsd-8]: Makefile audio.9 intro.9
src/sys/dev [netbsd-8]: audio.c
Added Files:
src/share/man/man9 [netbsd-8]: audio_system.9
Removed Files:
src/share/man/man7 [netbsd-8]: audio.7
Log Message:
Pull up following revision(s) (requested by nat in ticket #848):
share/man/man9/Makefile: revision 1.422
distrib/sets/lists/comp/mi: revision 1.2198
share/man/man7/Makefile: revision 1.33
share/man/man9/audio.9: revision 1.47
share/man/man7/audio.7: file removal
sys/dev/audio.c: revision 1.456
sys/dev/audio.c: revision 1.457
distrib/sets/lists/man/mi: revision 1.1591
share/man/man9/intro.9: revision 1.20
share/man/man7/audio.7: revision 1.3
share/man/man9/audio_system.9: revision 1.1
share/man/man7/intro.7: revision 1.26
share/man/man4/audio.4: revision 1.86
Fix a typo with sc_out/inports when setting the hardware recording gain on the
mix ring. Found by mrg@
XXX pullup-8
Using audioctl without the -p switch defaults to the mix ring. This allows
setting the hardware gain etc.
Update the audio spec in audio.7 to reflect these changes.
Addresses PR kern/52781.
Move the audio specification to section 9 under audio_system.
Ok wiz@
To generate a diff of this commit:
cvs rdiff -u -r1.2138.2.5 -r1.2138.2.6 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.1557.2.4 -r1.1557.2.5 src/distrib/sets/lists/man/mi
cvs rdiff -u -r1.79.2.2 -r1.79.2.3 src/share/man/man4/audio.4
cvs rdiff -u -r1.31.8.1 -r1.31.8.2 src/share/man/man7/Makefile
cvs rdiff -u -r1.2.2.2 -r0 src/share/man/man7/audio.7
cvs rdiff -u -r1.23.24.1 -r1.23.24.2 src/share/man/man7/intro.7
cvs rdiff -u -r1.414 -r1.414.2.1 src/share/man/man9/Makefile
cvs rdiff -u -r1.44.16.1 -r1.44.16.2 src/share/man/man9/audio.9
cvs rdiff -u -r0 -r1.1.2.2 src/share/man/man9/audio_system.9
cvs rdiff -u -r1.18 -r1.18.2.1 src/share/man/man9/intro.9
cvs rdiff -u -r1.357.2.12 -r1.357.2.13 src/sys/dev/audio.c
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2138.2.5 src/distrib/sets/lists/comp/mi:1.2138.2.6
--- src/distrib/sets/lists/comp/mi:1.2138.2.5 Sun Feb 11 21:17:33 2018
+++ src/distrib/sets/lists/comp/mi Thu Jun 7 18:24:15 2018
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2138.2.5 2018/02/11 21:17:33 snj Exp $
+# $NetBSD: mi,v 1.2138.2.6 2018/06/07 18:24:15 martin Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -10145,6 +10145,7 @@
./usr/share/man/cat9/arpresolve.0 comp-sys-catman .cat
./usr/share/man/cat9/atop.0 comp-sys-catman .cat
./usr/share/man/cat9/audio.0 comp-sys-catman .cat
+./usr/share/man/cat9/audio_system.0 comp-sys-catman .cat
./usr/share/man/cat9/autoconf.0 comp-sys-catman .cat
./usr/share/man/cat9/bawrite.0 comp-sys-catman .cat
./usr/share/man/cat9/bcdtobin.0 comp-sys-catman .cat
@@ -17631,6 +17632,7 @@
./usr/share/man/html9/arpresolve.html comp-sys-htmlman html
./usr/share/man/html9/atop.html comp-sys-htmlman html
./usr/share/man/html9/audio.html comp-sys-htmlman html
+./usr/share/man/html9/audio_system.html comp-sys-htmlman html
./usr/share/man/html9/autoconf.html comp-sys-htmlman html
./usr/share/man/html9/bawrite.html comp-sys-htmlman html
./usr/share/man/html9/bcdtobin.html comp-sys-htmlman html
@@ -25221,6 +25223,7 @@
./usr/share/man/man9/arpresolve.9 comp-sys-man .man
./usr/share/man/man9/atop.9 comp-sys-man .man
./usr/share/man/man9/audio.9 comp-sys-man .man
+./usr/share/man/man9/audio_system.9 comp-sys-man .man
./usr/share/man/man9/autoconf.9 comp-sys-man .man
./usr/share/man/man9/bawrite.9 comp-sys-man .man
./usr/share/man/man9/bcdtobin.9 comp-sys-man .man
Index: src/distrib/sets/lists/man/mi
diff -u src/distrib/sets/lists/man/mi:1.1557.2.4 src/distrib/sets/lists/man/mi:1.1557.2.5
--- src/distrib/sets/lists/man/mi:1.1557.2.4 Tue May 15 13:42:50 2018
+++ src/distrib/sets/lists/man/mi Thu Jun 7 18:24:16 2018
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1557.2.4 2018/05/15 13:42:50 martin Exp $
+# $NetBSD: mi,v 1.1557.2.5 2018/06/07 18:24:16 martin Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -2251,7 +2251,7 @@
./usr/share/man/cat5/wtmpx.0 man-sys-catman .cat
./usr/share/man/cat5/ypserv.acl.0 man-obsolete obsolete
./usr/share/man/cat7/ascii.0 man-reference-catman .cat
-./usr/share/man/cat7/audio.0 man-reference-catman .cat
+./usr/share/man/cat7/audio.0 man-obsolete obsolete
./usr/share/man/cat7/atf.0 man-atf-catman .cat,atf
./usr/share/man/cat7/c.0 man-reference-catman .cat
./usr/share/man/cat7/c78.0 man-reference-catman .cat
@@ -5272,7 +5272,7 @@
./usr/share/man/html5/wtmp.html man-sys-htmlman html
./usr/share/man/html5/wtmpx.html man-sys-htmlman html
./usr/share/man/html7/ascii.html man-reference-htmlman html
-./usr/share/man/html7/audio.html man-reference-htmlman html
+./usr/share/man/html7/audio.html man-obsolete obsolete
./usr/share/man/html7/atf.html man-atf-htmlman html,atf
./usr/share/man/html7/c.html man-reference-htmlman html
./usr/share/man/html7/c78.html man-reference-htmlman html
@@ -8263,7 +8263,7 @@
./usr/share/man/man5/wtmpx.5 man-sys-man .man
./usr/share/man/man5/ypserv.acl.5 man-obsolete obsolete
./usr/share/man/man7/ascii.7 man-reference-man .man
-./usr/share/man/man7/audio.7 man-reference-man .man
+./usr/share/man/man7/audio.7 man-obsolete obsolete
./usr/share/man/man7/atf.7 man-atf-man .man,atf
./usr/share/man/man7/c.7 man-reference-man .man
./usr/share/man/man7/c78.7 man-reference-man .man
Index: src/share/man/man4/audio.4
diff -u src/share/man/man4/audio.4:1.79.2.2 src/share/man/man4/audio.4:1.79.2.3
--- src/share/man/man4/audio.4:1.79.2.2 Tue May 15 13:42:50 2018
+++ src/share/man/man4/audio.4 Thu Jun 7 18:24:16 2018
@@ -1,4 +1,4 @@
-.\" $NetBSD: audio.4,v 1.79.2.2 2018/05/15 13:42:50 martin Exp $
+.\" $NetBSD: audio.4,v 1.79.2.3 2018/06/07 18:24:16 martin Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -790,7 +790,7 @@ string values.
.Ss USB
.Xr uaudio 4
.Ss The NetBSD audio specification
-.Xr audio 7
+.Xr audio_system 9
.Sh HISTORY
Support for virtual channels and mixing first appeared in
.Nx 8.0 .
Index: src/share/man/man7/Makefile
diff -u src/share/man/man7/Makefile:1.31.8.1 src/share/man/man7/Makefile:1.31.8.2
--- src/share/man/man7/Makefile:1.31.8.1 Tue May 15 13:42:49 2018
+++ src/share/man/man7/Makefile Thu Jun 7 18:24:16 2018
@@ -1,14 +1,14 @@
-# $NetBSD: Makefile,v 1.31.8.1 2018/05/15 13:42:49 martin Exp $
+# $NetBSD: Makefile,v 1.31.8.2 2018/06/07 18:24:16 martin Exp $
# @(#)Makefile 8.1 (Berkeley) 6/5/93
.include <bsd.init.mk>
# missing: eqnchar.7 man.7 ms.7 term.7
-MAN= ascii.7 audio.7 c.7 environ.7 glob.7 hier.7 hostname.7 intro.7 \
- mailaddr.7 module.7 nls.7 operator.7 orders.7 pkgsrc.7 release.7 \
- rfc6056.7 security.7 script.7 setuid.7 signal.7 src.7 sticky.7 \
- symlink.7 sysctl.7 tests.7
+MAN= ascii.7 c.7 environ.7 glob.7 hier.7 hostname.7 intro.7 mailaddr.7 \
+ module.7 nls.7 operator.7 orders.7 pkgsrc.7 release.7 rfc6056.7 \
+ security.7 script.7 setuid.7 signal.7 src.7 sticky.7 symlink.7 \
+ sysctl.7 tests.7
CLEANFILES= tests.7
.if ${MKKYUA} != "no"
Index: src/share/man/man7/intro.7
diff -u src/share/man/man7/intro.7:1.23.24.1 src/share/man/man7/intro.7:1.23.24.2
--- src/share/man/man7/intro.7:1.23.24.1 Tue May 15 13:42:49 2018
+++ src/share/man/man7/intro.7 Thu Jun 7 18:24:16 2018
@@ -1,4 +1,4 @@
-.\" $NetBSD: intro.7,v 1.23.24.1 2018/05/15 13:42:49 martin Exp $
+.\" $NetBSD: intro.7,v 1.23.24.2 2018/06/07 18:24:16 martin Exp $
.\"
.\" Copyright (c) 1983, 1990, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -42,9 +42,6 @@ This section contains miscellaneous docu
map of
.Tn ASCII
character set
-.It Xr audio 7
-the
-.Nx audio specification
.It Xr c 7
the C programming language
.It Xr environ 7
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.414 src/share/man/man9/Makefile:1.414.2.1
--- src/share/man/man9/Makefile:1.414 Sun May 21 19:07:29 2017
+++ src/share/man/man9/Makefile Thu Jun 7 18:24:15 2018
@@ -1,9 +1,9 @@
-# $NetBSD: Makefile,v 1.414 2017/05/21 19:07:29 abhinav Exp $
+# $NetBSD: Makefile,v 1.414.2.1 2018/06/07 18:24:15 martin Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
MAN= accept_filter.9 accf_data.9 accf_http.9 \
- altq.9 arp.9 audio.9 autoconf.9 \
+ altq.9 arp.9 audio.9 audio_system.9 autoconf.9 \
bcdtobin.9 bcmp.9 bcopy.9 bintime_add.9 bluetooth.9 boothowto.9 bpf.9 \
buffercache.9 bufferio.9 bufq.9 bus_dma.9 bus_space.9 byteorder.9 \
bzero.9 \
Index: src/share/man/man9/audio.9
diff -u src/share/man/man9/audio.9:1.44.16.1 src/share/man/man9/audio.9:1.44.16.2
--- src/share/man/man9/audio.9:1.44.16.1 Tue May 15 13:42:50 2018
+++ src/share/man/man9/audio.9 Thu Jun 7 18:24:15 2018
@@ -1,4 +1,4 @@
-.\" $NetBSD: audio.9,v 1.44.16.1 2018/05/15 13:42:50 martin Exp $
+.\" $NetBSD: audio.9,v 1.44.16.2 2018/06/07 18:24:15 martin Exp $
.\"
.\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -592,7 +592,7 @@ of class
.Dv AudioCmonitor .
.Sh SEE ALSO
.Xr audio 4 ,
-.Xr audio 7
+.Xr audio_system 9
.Sh HISTORY
This
.Nm
Index: src/share/man/man9/intro.9
diff -u src/share/man/man9/intro.9:1.18 src/share/man/man9/intro.9:1.18.2.1
--- src/share/man/man9/intro.9:1.18 Tue May 30 13:49:01 2017
+++ src/share/man/man9/intro.9 Thu Jun 7 18:24:15 2018
@@ -1,4 +1,4 @@
-.\" $NetBSD: intro.9,v 1.18 2017/05/30 13:49:01 abhinav Exp $
+.\" $NetBSD: intro.9,v 1.18.2.1 2018/06/07 18:24:15 martin Exp $
.\"
.\" Copyright (c) 1997, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -431,6 +431,11 @@ Interface between low and high level aud
See
.Xr audio 9 .
.Pp
+The
+.Nx audio specification.
+See
+.Xr audio_system 9 .
+.Pp
Bluetooth Device/Protocol API.
See
.Xr bluetooth 9 .
Index: src/sys/dev/audio.c
diff -u src/sys/dev/audio.c:1.357.2.12 src/sys/dev/audio.c:1.357.2.13
--- src/sys/dev/audio.c:1.357.2.12 Tue May 15 13:42:50 2018
+++ src/sys/dev/audio.c Thu Jun 7 18:24:16 2018
@@ -1,4 +1,4 @@
-/* $NetBSD: audio.c,v 1.357.2.12 2018/05/15 13:42:50 martin Exp $ */
+/* $NetBSD: audio.c,v 1.357.2.13 2018/06/07 18:24:16 martin Exp $ */
/*-
* Copyright (c) 2016 Nathanial Sloss <nathanialsl...@yahoo.com.au>
@@ -148,7 +148,7 @@
*/
#include <sys/cdefs.h>
-__KERNEL_RCSID(0, "$NetBSD: audio.c,v 1.357.2.12 2018/05/15 13:42:50 martin Exp $");
+__KERNEL_RCSID(0, "$NetBSD: audio.c,v 1.357.2.13 2018/06/07 18:24:16 martin Exp $");
#ifdef _KERNEL_OPT
#include "audio.h"
@@ -234,6 +234,8 @@ int audiosetinfo(struct audio_softc *, s
int audiogetinfo(struct audio_softc *, struct audio_info *, int,
struct virtual_channel *);
+int audioctl_open(dev_t, struct audio_softc *, int, int, struct lwp *,
+ struct file **);
int audio_open(dev_t, struct audio_softc *, int, int, struct lwp *,
struct file **);
int audio_close(struct audio_softc *, int, struct audio_chan *);
@@ -1677,9 +1679,11 @@ audioopen(dev_t dev, int flags, int ifmt
switch (AUDIODEV(dev)) {
case SOUND_DEVICE:
case AUDIO_DEVICE:
- case AUDIOCTL_DEVICE:
error = audio_open(dev, sc, flags, ifmt, l, &fp);
break;
+ case AUDIOCTL_DEVICE:
+ error = audioctl_open(dev, sc, flags, ifmt, l, &fp);
+ break;
case MIXER_DEVICE:
error = mixer_open(dev, sc, flags, ifmt, l, &fp);
break;
@@ -1713,9 +1717,11 @@ audioclose(struct file *fp)
switch (AUDIODEV(dev)) {
case SOUND_DEVICE:
case AUDIO_DEVICE:
- case AUDIOCTL_DEVICE:
error = audio_close(sc, fp->f_flag, chan);
break;
+ case AUDIOCTL_DEVICE:
+ error = 0;
+ break;
case MIXER_DEVICE:
error = mixer_close(sc, fp->f_flag, chan);
break;
@@ -2143,6 +2149,50 @@ audio_calcwater(struct audio_softc *sc,
}
int
+audioctl_open(dev_t dev, struct audio_softc *sc, int flags, int ifmt,
+ struct lwp *l, struct file **nfp)
+{
+ struct file *fp;
+ int error, fd;
+ const struct audio_hw_if *hw;
+ struct virtual_channel *vc;
+ struct audio_chan *chan;
+
+ KASSERT(mutex_owned(sc->sc_lock));
+
+ if (sc->sc_usemixer && !sc->sc_ready)
+ return ENXIO;
+
+ hw = sc->hw_if;
+ if (hw == NULL)
+ return ENXIO;
+
+ chan = kmem_zalloc(sizeof(struct audio_chan), KM_SLEEP);
+ if (sc->sc_usemixer)
+ vc = &sc->sc_mixring;
+ else
+ vc = sc->sc_hwvc;
+ chan->vc = vc;
+
+ error = fd_allocfile(&fp, &fd);
+ if (error)
+ goto bad;
+
+ chan->dev = dev;
+ chan->chan = 0;
+ chan->deschan = 0;
+
+ error = fd_clone(fp, fd, flags, &audio_fileops, chan);
+ KASSERT(error == EMOVEFD);
+
+ *nfp = fp;
+ return error;
+bad:
+ kmem_free(chan, sizeof(struct audio_chan));
+ return error;
+}
+
+int
audio_open(dev_t dev, struct audio_softc *sc, int flags, int ifmt,
struct lwp *l, struct file **nfp)
{
@@ -2174,9 +2224,6 @@ audio_open(dev_t dev, struct audio_softc
vc = sc->sc_hwvc;
chan->vc = vc;
- if (!sc->sc_usemixer && AUDIODEV(dev) == AUDIOCTL_DEVICE)
- goto audioctl_dev;
-
if (sc->sc_usemixer) {
vc->sc_open = 0;
vc->sc_mode = 0;
@@ -2294,12 +2341,9 @@ audio_open(dev_t dev, struct audio_softc
/* audio_close() decreases sc_mpr[n].usedlow, recalculate here */
audio_calcwater(sc, vc);
-audioctl_dev:
error = fd_allocfile(&fp, &fd);
if (error)
goto bad;
- if (!sc->sc_usemixer && AUDIODEV(dev) == AUDIOCTL_DEVICE)
- goto setup_chan;
DPRINTF(("audio_open: done sc_mode = 0x%x\n", vc->sc_mode));
@@ -2310,7 +2354,6 @@ audioctl_dev:
if (flags & FWRITE)
sc->sc_opens++;
-setup_chan:
chan->dev = dev;
chan->chan = n;
chan->deschan = n;
@@ -2487,9 +2530,6 @@ audio_close(struct audio_softc *sc, int
KASSERT(mutex_owned(sc->sc_lock));
- if (!sc->sc_usemixer && AUDIODEV(chan->dev) == AUDIOCTL_DEVICE)
- return 0;
-
if (sc->sc_opens == 0 && sc->sc_recopens == 0)
return ENXIO;
@@ -3085,7 +3125,7 @@ audio_ioctl(dev_t dev, struct audio_soft
} else
pchan = chan;
- if (chan->deschan != 0)
+ if (!sc->sc_usemixer || chan->deschan != 0)
vc = pchan->vc;
else
vc = &sc->sc_mixring;
@@ -4757,8 +4797,8 @@ done:
if (SPECIFIED(r->gain)) {
if (!sc->sc_usemixer || vc == &sc->sc_mixring) {
- au_get_gain(sc, &sc->sc_outports, &gain, &balance);
- error = au_set_gain(sc, &sc->sc_outports, r->gain, balance);
+ au_get_gain(sc, &sc->sc_inports, &gain, &balance);
+ error = au_set_gain(sc, &sc->sc_inports, r->gain, balance);
if (error)
goto cleanup;
} else
Added files:
Index: src/share/man/man9/audio_system.9
diff -u /dev/null src/share/man/man9/audio_system.9:1.1.2.2
--- /dev/null Thu Jun 7 18:24:17 2018
+++ src/share/man/man9/audio_system.9 Thu Jun 7 18:24:15 2018
@@ -0,0 +1,307 @@
+.\" $NetBSD: audio_system.9,v 1.1.2.2 2018/06/07 18:24:15 martin Exp $
+.\"
+.\" Copyright (c) 2016 - 2018 Nathanial Sloss <nathanialsl...@yahoo.com.au>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd May 28, 2018
+.Dt AUDIO_SYSTEM 9
+.Os
+.Sh NAME
+.Nm audio_system
+.Nd the
+.Nx
+in-kernel audio mixer specification
+.Sh INTRODUCTION
+This document aims to describe all aspects of the in-kernel audio mixer
+included with
+.Nx 8
+and onwards, describing its current behavior as of 2018.
+.Sh VIRTUAL CHANNEL (VCHAN)
+This is the most fundamental element to the mixer.
+The vchan has all of the properties of the traditional single open
+.Nx
+audio channel.
+It consists of playback and record rings along with
+.Vt audio_info
+structures.
+.Pp
+Upon opening of
+.Pa /dev/audio
+or
+.Pa /dev/sound ,
+a new vchan and mixerctl structure is created.
+In the case of
+.Pa /dev/sound ,
+.Vt audio_info
+structures are inherited from the last open of
+.Pa /dev/audio
+or
+.Pa /dev/sound .
+.Pp
+All vchans are up or down sampled into the mix ring (intermediate) format
+before being sent to hardware.
+.Pp
+It is described in the following diagram:
+.Bd -literal
+ VCHAN1---------\\
+ \\ VCHAN0
+ VCHAN2-------------MIX RING ---- HARDWARE
+ ... /
+ VCHANn---------/
+.Ed
+.Pp
+In the case of
+.Xr sysctl 8
+.Dv usemixer=0
+(see below), there is only one vchan whose play
+and record rings are the hardware play/record rings.
+.Pp
+User accessible vchans are numbered starting at one (1).
+Vchan 0 is used internally by the mixer for the mix ring and its ring buffers
+are not user accessible.
+.Pp
+The only limit to the number of open vchans is the speed of the computer and the
+number of free file descriptors.
+.Sh BLOCK - SIZE / LATENCY
+A block of audio data is the basic unit for audio data.
+Audio applications will not commence playback until three (3) blocks have been
+written - this is the source of latency in the mixer along with the size of the
+audio data block.
+.Pp
+For normal uses of audio read/write there will be three blocks of audio data before
+playback commences one in the vchan, one in the mix ring and one in the
+hardware ring.
+.Pp
+The size of the audio data block is dependent on the audio format configured
+by the application the latency
+.Xr sysctl 8
+and the underlying audio hardware.
+.Pp
+Some audio hardware devices only support a static block size, as such the
+overall latency of the mixer for these devices cannot be changed.
+Other devices such as those supported by
+.Xr hdaudio 4
+allow the hardware block size
+to be changed, allowing the latency of the mixer to change from 4
+milliseconds (ms) to 128 ms with the mixer intermediate format being 16 bit,
+stereo, 48 kHz.
+.Pp
+With regard to mmapped audio, blocks are played back immediately so the latency
+presented to applications is one third of the latency
+.Xr sysctl 8
+value.
+.Pp
+Latency can be calculated by the following formula:
+.Bd -literal
+ Latency (ms) = blocksize(bytes) * num blocks * 1000
+ --------------------------------------
+ freq(Hz) * bytes per sample * channels
+.Ed
+.Pp
+Latency in the mixer and latency presented to audio applications is consistent,
+it will be the same regardless of the audio format requested by the audio
+application.
+.Pp
+The default latency configured at boot time is 150ms and is subject to the above
+constraints.
+.Sh ADDED IOCTLS
+Two new ioctls have been added to accommodate mixing of multiple vchans:
+.Bl -tag -width indent
+.It Dv AUDIO_SETCHAN :
+Allows setting the target vchan to operate on for subsequent
+.Xr ioctl 2
+calls.
+.It Dv AUDIO_GETCHAN :
+Returns the current vchan number.
+.El
+.Pp
+These ioctls were necessary as some audio applications like to open an
+.Xr audio 4
+device and an
+.Xr audioctl 4
+device so to check on buffer usage and samples played etc.
+.Pp
+As opening an
+.Xr audioctl 4
+device would represent vchan 0 (the mix ring), these
+ioctls allow setting the target vchan and
+.Vt audio_info
+structure to that of an existing vchan.
+.Sh MIXERCTL INTERFACE / SOFTWARE VOLUME
+Mixerctl structures are allocated when a new vchan is created.
+The mixer control structure allows for setting the software volume for playback -
+.Li vchan.dacN
+or recording -
+.Li vchan.adcN .
+These are 8 bit values and the this value is applied during mixing into the mix
+ring.
+.Pp
+The software volume is applied to all channels (1, 2, 4 etc.) in the vchan and at
+present (2018-05-04) there are no balance controls for user accessible vchans.
+.Pp
+The first vchan corresponds to the
+.Li vchan.dac1/adc1
+mixer controls.
+.Pp
+All vchan mixer controls only have effect upon its own volume and writing to
+.Li outputs.master
+(or equivalent) control is required to change the volume of the hardware.
+.Pp
+Mixer controls are only present whilst the chan is in use and numbering starts
+at one (1).
+Mixer control numbers i.e.
+.Li dac/adc1
+correspond to their vchan number.
+.Sh AUDIOCTL / AUDIO_INFO INTERFACE
+Audioctl allows access to the
+.Vt audio_info
+structure of a given device.
+Due to the audio mixer a
+.Fl p
+flag was added to allow access to a given vchan's
+.Vt audio_info
+structure.
+The values for
+.Fl p
+are numbered starting at zero (0).
+.Pp
+Not specifying
+.Fl p
+is the same as specifying
+.Fl p Ar 0
+and will result in working with vchan 0 (the mix ring).
+This will display the audio parameters of the mix ring and allow
+setting the hardware gain and balance.
+.Pp
+This is for compatibility with existing applications and shell scripts
+that are unaware of the
+.Fl p
+switch.
+.Pp
+The parameters for playback and recording only effect the particular vchan
+being operated on (gain, sample rate, channels, encoding etc), except
+.Fl p Ar 0
+(the mix ring).
+.Sh ADDED SYSCTLS
+With the introduction of the audio mixer the following
+.Xr sysctl 7 Ns s
+have been added:
+.Bl -tag -width indent
+.It Li hw.driverN.frequency :
+.It Li hw.driverN.precision :
+.It Li hw.driverN.channels :
+Intermediate mixing format.
+(see below)
+.It Li hw.driverN.latency :
+Expressed in milliseconds.
+(see above)
+.It Li hw.driverN.multiuser :
+Off/On (0/1), defaults to off.
+This
+.Xr sysctl 7
+determines if multiple users are allowed to access the sound hardware.
+The root user is always allowed access (i.e., for wsbell).
+The first user to open the audio device has full control of the audio device
+if this sysctl is set to off.
+There currently is an outstanding PR about affecting a privileged process -
+PR/52627.
+.Pp
+Ideally if root intervenes with the audio device, it should do so unaffected.
+.Pp
+If this control is set to on, then all users' audio data are mixed and all users
+have access to the audio hardware.
+.It Li hw.driverN.usemixer :
+Off/On (0/1), defaults to on.
+This
+.Xr sysctl 7
+enables or disables the audio mixer.
+When set to off, the audio device can support only one vchan.
+This vchan's play and record ring buffers are the hardware ring buffers.
+.Pp
+This option was added to aid older/slower systems where the extra overhead of
+the audio mixer might pose a problem.
+.El
+.Sh INTERMEDIATE / MIXING FORMAT
+The initial concept was to handle incoming audio data similarly to that of a
+superheterodyne radio receiver:
+.Pp
+.Dl RF -> IF -> AF
+.Pp
+So the corresponding mixing concept is:
+.Pp
+.Dl vchan -> mixing format -> hardware
+.Pp
+The
+.Xr sysctl 7 Ns s
+described above determine the format for mixing.
+All vchans are up or down sampled to this format before mixing takes place.
+.Pp
+On most systems this defaults to 16 bit stereo 48kHz.
+The
+.Xr sysctl 7 Ns s
+governing the mixing format may only be changed when there are no
+vchans in use.
+.Pp
+On faster systems the precision (8, 16, 32 bits) may be changed along with the
+sample rate and number of channels (mono, stereo, 4 etc.).
+.Pp
+On older/slower systems utilizing audio mixing, it may be required to lower the
+quality of this format to ease the amount of data processing whilst mixing.
+.Pp
+All possible audio formats (mulaw, alaw, slinear, ulinear, 8, 16, and 32 bit
+precision) are converted for use by the audio mixer.
+.Sh MEMORY MAPPED PLAYBACK
+It is possible to use mmap for audio playback, achieving reduced latency.
+However the audio applications selected format must match the
+mixing/intermediate format (see above).
+.Pp
+It is possible to obtain the
+.Vt audio_info
+for vchan0 which contains the
+intermediate/mixing format to ease applications configuring for mmapped audio.
+.Pp
+At present most applications don't use the mix ring's
+.Vt audio_info
+structure to obtain the requiredplay back parameters and some user
+intervention is required to set the audio format for the application.
+.Sh HARDWARE DRIVER REQUIREMENTS
+Audio mixing requires signed linear support in the host's endianness.
+Driver authors should support slinear_le and slinear_be formats.
+.Pp
+If the audio hardware is intended to be used with the mixer disabled, mulaw 1ch
+8000 hz needs to be supported also.
+.Pp
+This is easily achievable with the auconv framework/filters.
+All new drivers should consider the use of auconv where possible.
+.Sh SEE ALSO
+.Xr audioctl 1 ,
+.Xr mixerctl 1 ,
+.Xr audio 4 ,
+.Xr audio 9
+.Sh AUTHORS
+.An Nathanial Sloss
+.Sh SPECIAL THANKS
+Great appreciation goes to Onno van der Linden, isaki@, maya@, jmcneill@,
+pgoyette@, mrg@, riastradh@ and christos@ \(em without their input, this code would
+not be what it is currently.
