[src/trunk]: src/share/man/man7 Various improvements, more marku...

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/6f13646d9d6d
branches:  trunk
changeset: 319071:6f13646d9d6d
user:      wiz <wiz%NetBSD.org@localhost>
date:      Tue May 15 09:30:01 2018 +0000

description:
Various improvements, more markup, typo fixes.

diffstat:

 share/man/man7/audio.7 |  207 +++++++++++++++++++++++++++++++-----------------
 1 files changed, 132 insertions(+), 75 deletions(-)

diffs (truncated from 327 to 300 lines):

diff -r 635585741a26 -r 6f13646d9d6d share/man/man7/audio.7
--- a/share/man/man7/audio.7    Tue May 15 09:13:36 2018 +0000
+++ b/share/man/man7/audio.7    Tue May 15 09:30:01 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: audio.7,v 1.1 2018/05/15 00:54:01 nat Exp $
+.\"    $NetBSD: audio.7,v 1.2 2018/05/15 09:30:01 wiz Exp $
 .\"
 .\" Copyright (c) 2016 - 2018  Nathanial Sloss <nathanialsloss%yahoo.com.au@localhost>
 .\" All rights reserved.
@@ -35,19 +35,29 @@
 .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.
+.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.
+It consists of playback and record rings along with
+.Vt 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.
+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.
@@ -61,37 +71,46 @@
        VCHANn---------/
 .Ed
 .Pp
-In the case of sysctl usemixer=0 (see below) there is only one vchan whose play
+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 internaly by the mixer for the mix ring and its ring buffers
+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 play back until three(3) blocks have been
+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 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
+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 sysctl and the underlying audio hardware.
+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 hdaudio allow the hardware block size
+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,
+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.
+presented to applications is one third of the latency
+.Xr sysctl 8
+value.
 .Pp
 Latency can be calculated by the following formula:
 .Bd -literal
@@ -109,72 +128,101 @@
 .Sh ADDED IOCTLS
 Two new ioctls have been added to accommodate mixing of multiple vchans:
 .Bl -tag -width indent
-.It Ar AUDIO_SETCHAN:
+.It Dv AUDIO_SETCHAN :
 Allows setting the target vchan to operate on for subsequent
-ioctl calls.
-.It Ar AUDIO_GETCHAN:
+.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 audio
-device and a audioctl device so to check on buffer usage and samples played etc.
+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 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.
+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 play
-back - vchan.dacN or recording - vchan.adcN.
+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) their are no balance controls for user accessible vchans.
+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 vchan.dac1/adc1 mixer controls.
+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
-outputs.master (or equivalent) control is required to change the volume of the
-hardware.
+.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 ie dac/adc1 correspond to their vchan number.
+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 audio_info structure of a given device.
+Audioctl allows access to the
+.Vt 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).
+.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 -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:
+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 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
+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 sysctls have been added:
+With the introduction of the audio mixer the following
+.Xr sysctl 7 Ns s
+have been added:
 .Bl -tag -width indent
-.It Ar hw.driverN.frequency:
-.It Ar hw.driverN.precision:
-.It Ar hw.driverN.channels:
+.It Li hw.driverN.frequency :
+.It Li hw.driverN.precision :
+.It Li hw.driverN.channels :
 Intermediate mixing format.
 (see below)
-.It Ar hw.driverN.latency:
+.It Li 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).
+.It Li hw.driverN.multiuser :
+Off/On (0/1), defaults to off.
+This
+.Xr sysctl 7
+determines if multiple users are allowed to access the sound hardware.
+The root user is always allowed access (i.e., 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 -
@@ -184,10 +232,12 @@
 .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.
+.It Li hw.driverN.usemixer :
+Off/On (0/1), defaults to on.
+This
+.Xr sysctl 7
+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
@@ -203,37 +253,44 @@
 .Pp
 .Dl            vchan -> mixing format -> hardware
 .Pp
-The sysctls described above determine the format for mixing.
+The
+.Xr sysctl 7 Ns s
+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
+The
+.Xr sysctl 7 Ns s
+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).
+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
+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
+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
+.Sh MEMORY MAPPED PLAYBACK
 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).
+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
+It is possible to obtain the
+.Vt audio_info
+for vchan0 which contains the
 intermediate/mixing format to ease applications configuring for mmapped audio.