Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/netbsd-8]: src Pull up following revision(s) (requested by nat in ticket...
details: https://anonhg.NetBSD.org/src/rev/c50bc742664c
branches: netbsd-8
changeset: 851732:c50bc742664c
user: martin <martin%NetBSD.org@localhost>
date: Tue May 15 13:42:49 2018 +0000
description:
Pull up following revision(s) (requested by nat in ticket #825):
share/man/man7/Makefile: revision 1.32
share/man/man9/audio.9: revision 1.46
sys/dev/audio.c: revision 1.453
sys/dev/audio.c: revision 1.454
sys/dev/audio.c: revision 1.455
share/man/man7/audio.7: revision 1.1
share/man/man7/audio.7: revision 1.2
share/man/man7/intro.7: revision 1.24
share/man/man4/audio.4: revision 1.85
distrib/sets/lists/man/mi: revision 1.1586
Fix numbering of vchan mixer controls to correspond to the vchan number in
use.
This makes the numbering of vchans consistient for audioctl and mixerctl.
Expose the audio_info structure of vchan zero(0) the mix ring to allow
setting the hardware gain and balance via audioctl(1) using the -p 0
switch.
It is not possible to influence the hardware gain/blance from the
audio_info structure of vchans 1 onwards. It is now possible to return
the audio mixers audio format from the audio_info structure of vchan 0 to
ease applications configuring for mmapped play back.
This is conformant to the audio specification posted on tech-kern see:
"NetBSD Audio Specification 2018"
or audio.7 manual page to be added in a follow up commit.
Add the audio mixer specification to section 7 of the manual.
See posting on tech-kern - "NetBSD Audio Specification 2018."
Update the introduction page to section 7 of the manual noting the audio
spec.
Various improvements, more markup, typo fixes.
Fix over cautious compiler error - setmode may not be initialized.
diffstat:
distrib/sets/lists/man/mi | 5 +-
share/man/man4/audio.4 | 6 +-
share/man/man7/Makefile | 10 +-
share/man/man7/audio.7 | 308 ++++++++++++++++++++++++++++++++++++++++++++++
share/man/man7/intro.7 | 7 +-
share/man/man9/audio.9 | 7 +-
sys/dev/audio.c | 113 ++++++++++++---
7 files changed, 417 insertions(+), 39 deletions(-)
diffs (truncated from 669 to 300 lines):
diff -r 319c01ae7703 -r c50bc742664c distrib/sets/lists/man/mi
--- a/distrib/sets/lists/man/mi Tue May 15 13:37:24 2018 +0000
+++ b/distrib/sets/lists/man/mi Tue May 15 13:42:49 2018 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1557.2.3 2018/05/12 10:35:45 martin Exp $
+# $NetBSD: mi,v 1.1557.2.4 2018/05/15 13:42:50 martin Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -2251,6 +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/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
@@ -5271,6 +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/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
@@ -8261,6 +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/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 319c01ae7703 -r c50bc742664c share/man/man4/audio.4
--- a/share/man/man4/audio.4 Tue May 15 13:37:24 2018 +0000
+++ b/share/man/man4/audio.4 Tue May 15 13:42:49 2018 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: audio.4,v 1.79.2.1 2018/01/15 00:08:55 snj Exp $
+.\" $NetBSD: audio.4,v 1.79.2.2 2018/05/15 13:42:50 martin 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
@@ -789,6 +789,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 319c01ae7703 -r c50bc742664c share/man/man7/Makefile
--- a/share/man/man7/Makefile Tue May 15 13:37:24 2018 +0000
+++ b/share/man/man7/Makefile Tue May 15 13:42:49 2018 +0000
@@ -1,14 +1,14 @@
-# $NetBSD: Makefile,v 1.31 2014/12/02 03:51:48 msaitoh Exp $
+# $NetBSD: Makefile,v 1.31.8.1 2018/05/15 13:42:49 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 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 319c01ae7703 -r c50bc742664c share/man/man7/audio.7
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man7/audio.7 Tue May 15 13:42:49 2018 +0000
@@ -0,0 +1,308 @@
+.\" $NetBSD: audio.7,v 1.2.2.2 2018/05/15 13:42:49 martin 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
+.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 result in a new vchan being created, 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
+will result in working with a new vchan and this is only
+desired when the next subsequent audio open is to be
+.Pa /dev/sound ,
+i.e.:
+.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 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).
+Specifying
+.Fl p Ar 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
+.Xr sysctl 7 Ns s
+have been added:
+.Bl -tag -width indent
+.It Li hw.driverN.frequency :
+.It Li hw.driverN.precision :
Home |
Main Index |
Thread Index |
Old Index