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/80d733304d3f
branches:  netbsd-8
changeset: 434996:80d733304d3f
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 aa9f4cbd9a3a -r 80d733304d3f 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 aa9f4cbd9a3a -r 80d733304d3f 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 aa9f4cbd9a3a -r 80d733304d3f 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 aa9f4cbd9a3a -r 80d733304d3f 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