Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Add the audio mixer specification to section 7 ...
details: https://anonhg.NetBSD.org/src/rev/b82e4cd220ed
branches: trunk
changeset: 319059:b82e4cd220ed
user: nat <nat%NetBSD.org@localhost>
date: Tue May 15 00:54:01 2018 +0000
description:
Add the audio mixer specification to section 7 of the manual.
See posting on tech-kern - "NetBSD Audio Specification 2018."
diffstat:
distrib/sets/lists/man/mi | 5 +-
share/man/man4/audio.4 | 6 +-
share/man/man7/Makefile | 10 +-
share/man/man7/audio.7 | 251 ++++++++++++++++++++++++++++++++++++++++++++++
share/man/man9/audio.9 | 7 +-
5 files changed, 268 insertions(+), 11 deletions(-)
diffs (truncated from 366 to 300 lines):
diff -r 75cf0e381fd9 -r b82e4cd220ed distrib/sets/lists/man/mi
--- a/distrib/sets/lists/man/mi Tue May 15 00:44:56 2018 +0000
+++ b/distrib/sets/lists/man/mi Tue May 15 00:54:01 2018 +0000
@@ -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
diff -r 75cf0e381fd9 -r b82e4cd220ed share/man/man4/audio.4
--- a/share/man/man4/audio.4 Tue May 15 00:44:56 2018 +0000
+++ b/share/man/man4/audio.4 Tue May 15 00:54:01 2018 +0000
@@ -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 @@
.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 .
diff -r 75cf0e381fd9 -r b82e4cd220ed share/man/man7/Makefile
--- a/share/man/man7/Makefile Tue May 15 00:44:56 2018 +0000
+++ b/share/man/man7/Makefile Tue May 15 00:54:01 2018 +0000
@@ -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"
diff -r 75cf0e381fd9 -r b82e4cd220ed share/man/man7/audio.7
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man7/audio.7 Tue May 15 00:54:01 2018 +0000
@@ -0,0 +1,251 @@
+.\" $NetBSD: audio.7,v 1.1 2018/05/15 00:54:01 nat Exp $
+.\"
+.\" Copyright (c) 2016 - 2018 Nathanial Sloss <nathanialsloss%yahoo.com.au@localhost>
+.\" 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
Home |
Main Index |
Thread Index |
Old Index