Module Name: src
Committed By: nat
Date: Tue May 15 00:54:02 UTC 2018
Modified Files:
src/distrib/sets/lists/man: mi
src/share/man/man4: audio.4
src/share/man/man7: Makefile
src/share/man/man9: audio.9
Added Files:
src/share/man/man7: audio.7
Log Message:
Add the audio mixer specification to section 7 of the manual.
See posting on tech-kern - "NetBSD Audio Specification 2018."
To generate a diff of this commit:
cvs rdiff -u -r1.1585 -r1.1586 src/distrib/sets/lists/man/mi
cvs rdiff -u -r1.84 -r1.85 src/share/man/man4/audio.4
cvs rdiff -u -r1.31 -r1.32 src/share/man/man7/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man7/audio.7
cvs rdiff -u -r1.45 -r1.46 src/share/man/man9/audio.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/man/mi
diff -u src/distrib/sets/lists/man/mi:1.1585 src/distrib/sets/lists/man/mi:1.1586
--- src/distrib/sets/lists/man/mi:1.1585 Wed May 9 05:59:28 2018
+++ src/distrib/sets/lists/man/mi Tue May 15 00:54:01 2018
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1585 2018/05/09 05:59:28 msaitoh Exp $
+# $NetBSD: mi,v 1.1586 2018/05/15 00:54:01 nat Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -2267,6 +2267,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/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
@@ -5308,6 +5309,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/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
@@ -8319,6 +8321,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/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.84 src/share/man/man4/audio.4:1.85
--- src/share/man/man4/audio.4:1.84 Sat Jan 13 19:57:35 2018
+++ src/share/man/man4/audio.4 Tue May 15 00:54:01 2018
@@ -1,4 +1,4 @@
-.\" $NetBSD: audio.4,v 1.84 2018/01/13 19:57:35 uwe Exp $
+.\" $NetBSD: audio.4,v 1.85 2018/05/15 00:54:01 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 October 27, 2017
+.Dd May 15, 2018
.Dt AUDIO 4
.Os
.Sh NAME
@@ -811,6 +811,8 @@ string values.
.Xr bba 4
.Ss USB
.Xr uaudio 4
+.Ss The NetBSD audio specification
+.Xr audio 7
.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 src/share/man/man7/Makefile:1.32
--- src/share/man/man7/Makefile:1.31 Tue Dec 2 03:51:48 2014
+++ src/share/man/man7/Makefile Tue May 15 00:54:01 2018
@@ -1,14 +1,14 @@
-# $NetBSD: Makefile,v 1.31 2014/12/02 03:51:48 msaitoh Exp $
+# $NetBSD: Makefile,v 1.32 2018/05/15 00:54:01 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 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 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
CLEANFILES= tests.7
.if ${MKKYUA} != "no"
Index: src/share/man/man9/audio.9
diff -u src/share/man/man9/audio.9:1.45 src/share/man/man9/audio.9:1.46
--- src/share/man/man9/audio.9:1.45 Mon Jul 3 21:28:48 2017
+++ src/share/man/man9/audio.9 Tue May 15 00:54:01 2018
@@ -1,4 +1,4 @@
-.\" $NetBSD: audio.9,v 1.45 2017/07/03 21:28:48 wiz Exp $
+.\" $NetBSD: audio.9,v 1.46 2018/05/15 00:54:01 nat Exp $
.\"
.\" Copyright (c) 1999, 2000 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 July 13, 2014
+.Dd May 15, 2018
.Dt AUDIO 9
.Os
.Sh NAME
@@ -591,7 +591,8 @@ and that is a control named
of class
.Dv AudioCmonitor .
.Sh SEE ALSO
-.Xr audio 4
+.Xr audio 4 ,
+.Xr audio 7
.Sh HISTORY
This
.Nm
Added files:
Index: src/share/man/man7/audio.7
diff -u /dev/null src/share/man/man7/audio.7:1.1
--- /dev/null Tue May 15 00:54:02 2018
+++ src/share/man/man7/audio.7 Tue May 15 00:54:01 2018
@@ -0,0 +1,251 @@
+.\" $NetBSD: audio.7,v 1.1 2018/05/15 00:54:01 nat 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 4, 2018
+.Dt AUDIO 7
+.Os
+.Sh NAME
+.Nm audio
+.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 audio_info structures.
+.Pp
+Upon opening of /dev/audio or /dev/sound a new vchan and mixerctl structure is
+created.
+In the case of /dev/sound, audio_info structures are inherited from the last
+open of /dev/audio or /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 sysctl 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 internaly 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 play back 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 audio read/write their will be three blocks of audio data before
+play back 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 sysctl 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 hdaudio 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 sysctl 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 Ar AUDIO_SETCHAN:
+Allows setting the target vchan to operate on for subsequent
+ioctl calls.
+.It Ar AUDIO_GETCHAN:
+Returns the current vchan number.
+.El
+.Pp
+These ioctls were necessary as some audio applications like to open an audio
+device and a audioctl device so to check on buffer usage and samples played etc.
+.Pp
+As opening an audioctl device would result in a new vchan being created, these
+ioctls allow setting the target vchan and 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 play
+back - vchan.dacN or recording - 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) their are no balance controls for user accessible vchans.
+.Pp
+The first vchan corresponds to the vchan.dac1/adc1 mixer controls.
+.Pp
+All vchan mixer controls only have effect upon its own volume and writing to
+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 ie dac/adc1 correspond to their vchan number.
+.Sh AUDIOCTL / AUDIO_INFO INTERFACE
+Audioctl allows access to the audio_info structure of a given device.
+Due to the audio mixer a
+.Em -p
+switch was added to allow access to a given vchan's audio_info structure.
+The values for -p are numbered starting at zero(0).
+.Pp
+Not specifying -p will result in working with a new vchan and this is only
+desired when the next subsequent audio open is to be /dev/sound. ie:
+.Pp
+.Dl audioctl -w play.gain=120
+.Dl open /dev/sound this will have an initial software volume level of 120.
+.Pp
+The parameters for play back and recording only effect the particular vchan
+being operated on (gain, sample rate, channels, encoding etc), except -p 0 (the
+mix ring).
+Specifying -p 0 will display the audio parameters of the mix ring and allow
+setting the hardware gain and balance.
+.Sh ADDED SYSCTLS
+With the introduction of the audio mixer the following sysctls have been added:
+.Bl -tag -width indent
+.It Ar hw.driverN.frequency:
+.It Ar hw.driverN.precision:
+.It Ar hw.driverN.channels:
+Intermediate mixing format.
+(see below)
+.It Ar hw.driverN.latency:
+Expressed in milliseconds.
+(see above)
+.It Ar hw.driverN.multiuser:
+Off/On (0/1) defaults to off.
+This sysctl determines if multiple users are allowed to access the sound
+hardware.
+The root user is always allowed access (ie 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 Ar hw.driverN.usemixer:
+Off/On (0/1) defaults to on.
+This sysctl 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 sysctls 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 sysctls 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 PLAY BACK
+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 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 audio_info structure to
+obtain the required play 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 hosts' 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@, jmcneil@,
+pgoyette@, mrg@, riastradh@ and christos@, without their input, this code would
+not be what it is currently.
