Module Name: src
Committed By: nat
Date: Mon May 28 00:18:06 UTC 2018
Modified Files:
src/distrib/sets/lists/comp: mi
src/distrib/sets/lists/man: mi
src/share/man/man4: audio.4
src/share/man/man7: Makefile intro.7
src/share/man/man9: Makefile audio.9 intro.9
Added Files:
src/share/man/man9: audio_system.9
Removed Files:
src/share/man/man7: audio.7
Log Message:
Move the audio specification to section 9 under audio_system.
Ok wiz@
To generate a diff of this commit:
cvs rdiff -u -r1.2197 -r1.2198 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.1590 -r1.1591 src/distrib/sets/lists/man/mi
cvs rdiff -u -r1.85 -r1.86 src/share/man/man4/audio.4
cvs rdiff -u -r1.32 -r1.33 src/share/man/man7/Makefile
cvs rdiff -u -r1.4 -r0 src/share/man/man7/audio.7
cvs rdiff -u -r1.25 -r1.26 src/share/man/man7/intro.7
cvs rdiff -u -r1.421 -r1.422 src/share/man/man9/Makefile
cvs rdiff -u -r1.46 -r1.47 src/share/man/man9/audio.9
cvs rdiff -u -r0 -r1.1 src/share/man/man9/audio_system.9
cvs rdiff -u -r1.19 -r1.20 src/share/man/man9/intro.9
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.2197 src/distrib/sets/lists/comp/mi:1.2198
--- src/distrib/sets/lists/comp/mi:1.2197 Sun May 27 21:09:39 2018
+++ src/distrib/sets/lists/comp/mi Mon May 28 00:18:05 2018
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2197 2018/05/27 21:09:39 maya Exp $
+# $NetBSD: mi,v 1.2198 2018/05/28 00:18:05 nat Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -10415,6 +10415,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
@@ -18123,6 +18124,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
@@ -25935,6 +25937,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.1590 src/distrib/sets/lists/man/mi:1.1591
--- src/distrib/sets/lists/man/mi:1.1590 Sun May 27 05:31:20 2018
+++ src/distrib/sets/lists/man/mi Mon May 28 00:18:05 2018
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1590 2018/05/27 05:31:20 thorpej Exp $
+# $NetBSD: mi,v 1.1591 2018/05/28 00:18:05 nat Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -2270,7 +2270,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
@@ -5315,7 +5315,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
@@ -8330,7 +8330,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.85 src/share/man/man4/audio.4:1.86
--- src/share/man/man4/audio.4:1.85 Tue May 15 00:54:01 2018
+++ src/share/man/man4/audio.4 Mon May 28 00:18:05 2018
@@ -1,4 +1,4 @@
-.\" $NetBSD: audio.4,v 1.85 2018/05/15 00:54:01 nat Exp $
+.\" $NetBSD: audio.4,v 1.86 2018/05/28 00:18:05 nat Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -812,7 +812,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.32 src/share/man/man7/Makefile:1.33
--- src/share/man/man7/Makefile:1.32 Tue May 15 00:54:01 2018
+++ src/share/man/man7/Makefile Mon May 28 00:18:06 2018
@@ -1,14 +1,14 @@
-# $NetBSD: Makefile,v 1.32 2018/05/15 00:54:01 nat Exp $
+# $NetBSD: Makefile,v 1.33 2018/05/28 00:18:06 nat 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.25 src/share/man/man7/intro.7:1.26
--- src/share/man/man7/intro.7:1.25 Tue May 15 09:13:36 2018
+++ src/share/man/man7/intro.7 Mon May 28 00:18:06 2018
@@ -1,4 +1,4 @@
-.\" $NetBSD: intro.7,v 1.25 2018/05/15 09:13:36 wiz Exp $
+.\" $NetBSD: intro.7,v 1.26 2018/05/28 00:18:06 nat Exp $
.\"
.\" Copyright (c) 1983, 1990, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -40,9 +40,6 @@ This section contains miscellaneous docu
.Bl -tag -width "mdoc.samples(7)" -offset indent
.It Xr ascii 7
map of 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.421 src/share/man/man9/Makefile:1.422
--- src/share/man/man9/Makefile:1.421 Sun May 27 21:09:39 2018
+++ src/share/man/man9/Makefile Mon May 28 00:18:06 2018
@@ -1,9 +1,9 @@
-# $NetBSD: Makefile,v 1.421 2018/05/27 21:09:39 maya Exp $
+# $NetBSD: Makefile,v 1.422 2018/05/28 00:18:06 nat 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.46 src/share/man/man9/audio.9:1.47
--- src/share/man/man9/audio.9:1.46 Tue May 15 00:54:01 2018
+++ src/share/man/man9/audio.9 Mon May 28 00:18:06 2018
@@ -1,4 +1,4 @@
-.\" $NetBSD: audio.9,v 1.46 2018/05/15 00:54:01 nat Exp $
+.\" $NetBSD: audio.9,v 1.47 2018/05/28 00:18:06 nat 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.19 src/share/man/man9/intro.9:1.20
--- src/share/man/man9/intro.9:1.19 Sun Nov 12 21:07:15 2017
+++ src/share/man/man9/intro.9 Mon May 28 00:18:06 2018
@@ -1,4 +1,4 @@
-.\" $NetBSD: intro.9,v 1.19 2017/11/12 21:07:15 riastradh Exp $
+.\" $NetBSD: intro.9,v 1.20 2018/05/28 00:18:06 nat Exp $
.\"
.\" Copyright (c) 1997, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -435,6 +435,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 .
Added files:
Index: src/share/man/man9/audio_system.9
diff -u /dev/null src/share/man/man9/audio_system.9:1.1
--- /dev/null Mon May 28 00:18:06 2018
+++ src/share/man/man9/audio_system.9 Mon May 28 00:18:06 2018
@@ -0,0 +1,307 @@
+.\" $NetBSD: audio_system.9,v 1.1 2018/05/28 00:18:06 nat Exp $
+.\"
+.\" Copyright (c) 2016 - 2018 Nathanial Sloss <[email protected]>
+.\" 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.
