Source-Changes-HG archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

[src/trunk]: src Move the audio specification to section 9 under audio_system.



details:   https://anonhg.NetBSD.org/src/rev/e0640d2a8fda
branches:  trunk
changeset: 322998:e0640d2a8fda
user:      nat <nat%NetBSD.org@localhost>
date:      Mon May 28 00:18:05 2018 +0000

description:
Move the audio specification to section 9 under audio_system.

Ok wiz@

diffstat:

 distrib/sets/lists/comp/mi    |    5 +-
 distrib/sets/lists/man/mi     |    8 +-
 share/man/man4/audio.4        |    4 +-
 share/man/man7/Makefile       |   10 +-
 share/man/man7/audio.7        |  307 ------------------------------------------
 share/man/man7/intro.7        |    5 +-
 share/man/man9/Makefile       |    4 +-
 share/man/man9/audio.9        |    4 +-
 share/man/man9/audio_system.9 |  307 ++++++++++++++++++++++++++++++++++++++++++
 share/man/man9/intro.9        |    7 +-
 10 files changed, 333 insertions(+), 328 deletions(-)

diffs (truncated from 805 to 300 lines):

diff -r 8635b848bbf7 -r e0640d2a8fda distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Sun May 27 21:09:39 2018 +0000
+++ b/distrib/sets/lists/comp/mi        Mon May 28 00:18:05 2018 +0000
@@ -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
diff -r 8635b848bbf7 -r e0640d2a8fda distrib/sets/lists/man/mi
--- a/distrib/sets/lists/man/mi Sun May 27 21:09:39 2018 +0000
+++ b/distrib/sets/lists/man/mi Mon May 28 00:18:05 2018 +0000
@@ -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
diff -r 8635b848bbf7 -r e0640d2a8fda share/man/man4/audio.4
--- a/share/man/man4/audio.4    Sun May 27 21:09:39 2018 +0000
+++ b/share/man/man4/audio.4    Mon May 28 00:18:05 2018 +0000
@@ -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 @@
 .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 .
diff -r 8635b848bbf7 -r e0640d2a8fda share/man/man7/Makefile
--- a/share/man/man7/Makefile   Sun May 27 21:09:39 2018 +0000
+++ b/share/man/man7/Makefile   Mon May 28 00:18:05 2018 +0000
@@ -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"
diff -r 8635b848bbf7 -r e0640d2a8fda share/man/man7/audio.7
--- a/share/man/man7/audio.7    Sun May 27 21:09:39 2018 +0000
+++ /dev/null   Thu Jan 01 00:00:00 1970 +0000
@@ -1,307 +0,0 @@
-.\"    $NetBSD: audio.7,v 1.4 2018/05/23 07:08:13 wiz 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 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



Home | Main Index | Thread Index | Old Index