- Update the Runtime Configuration, FILES and DIAGNOSTICS sections to

the new world order.
-  Use our standard section 4 SYNOPSIS.
-  Minor nits.

Reviewed by:	brueffer, ariff

share/man/man4/pcm.4

@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd October 14, 2006
+.Dd November 26, 2006
 .Dt SOUND 4
 .Os
 .Sh NAME
@@ -36,13 +36,13 @@
 .Fx
 PCM audio device infrastructure
 .Sh SYNOPSIS
-For a card with bridge driver support, and a PnP card:
+To compile this driver into the kernel, place the following line in your
+kernel configuration file:
 .Bd -ragged -offset indent
 .Cd "device sound"
 .Ed
 .Pp
-For a card without bridge driver support, and a non-PnP card,
-the following lines may be required in
+Non-PnP sound cards require the following lines in
 .Xr device.hints 5 :
 .Bd -literal -offset indent
 hint.pcm.0.at="isa"
@@ -68,10 +68,10 @@ driver provides support for
 audio play and capture.
 This driver also supports various
 .Tn PCI ,
+.Tn ISA ,
 .Tn WSS/MSS
-compatible,
-.Tn ISA
-sound cards, and AC97 mixer.
+compatible
+sound cards, AC97 mixer and High Definition Audio.
 Once the
 .Nm
 driver attaches, supported devices provide audio record and
@@ -82,7 +82,7 @@ sound system provides dynamic mixing
 .Dq VCHAN
 and rate conversion
 .Dq soft formats .
-True full duplex operation is available on most cards.
+True full duplex operation is available on most sound cards.
 .Pp
 If the sound card is supported by a bridge driver, the
 .Nm
@@ -162,42 +162,51 @@ options can be configured via the
 .Xr sysctl 8
 interface but can only be manipulated while the device is inactive.
 .Ss Runtime Configuration
-The following
+There are a number of
 .Xr sysctl 8
-variables are available:
+variables available.
+.Va hw.snd.*
+tunables are global settings and
+.Va dev.pcm.*
+are device specific.
 .Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent
-.It Va hw.snd.pcm%d.buffersize
-Configure the amount of
-.Tn DMA
-bufferspace available for a device.
-.It Va hw.snd.targetirqrate
-Set the default block size such that continuous
-playback will achieve this
-.Tn IRQ
-rate.
-This value can be tuned to improve application performance.
-Increase this value when the sound lags and decrease
-it if sound stutters or breaks up.
-.It Va hw.snd.unit
-When using
-.Xr devfs 5 ,
-the default device for
-.Pa /dev/dsp .
-Equivalent to a symlink from
-.Pa /dev/dsp
-to
-.Pa /dev/dsp Ns Va ${hw.snd.unit} .
+.It Va hw.snd.latency_profile
+Define sets of buffering latency conversion tables for the
+.Va hw.snd.latency
+tunable.
+A value of 0 will use a low and aggressive latency profile which can result
+in possible underruns if the application cannot keep up with a rapid irq
+rate, especially during high workload.
+The default value is 1, which is considered a moderate/safe latency profile.
+.It Va hw.snd.latency
+Configure the buffering latency.
+Only affects applications that do not explicitly request
+blocksize / fragments.
+This tunable provides finer granularity than the
+.Va hw.snd.latency_profile
+tunable.
+Possible values range between 0 (lowest latency) and 10 (highest latency).
 .It Va hw.snd.report_soft_formats
 Controls the internal format conversion if it is
 available transparently to the application software.
 When disabled or not available, the application will
 only be able to select formats the device natively supports.
+.It Va hw.snd.feeder_rate_round
+Sample rate rounding threshold, to avoid large prime division at the
+cost of accuracy.
+All requested sample rates will be rounded to the nearest threshold value.
+Possible values range between 0 (disabled) and 500.
+Default is 25.
+.It Va hw.snd.feeder_rate_max
+Maximum allowable sample rate.
+.It Va hw.snd.feeder_rate_min
+Minimum allowable sample rate.
 .It Va hw.snd.verbose
 Level of verbosity for the
 .Pa /dev/sndstat
 device.
 Higher values include more output and the highest level,
-three, should be used when reporting problems.
+four, should be used when reporting problems.
 Other options include:
 .Bl -tag -width 2n
 .It 0
@@ -210,12 +219,14 @@ Channel information per device including the channel's
 current format, speed, and pseudo device statistics such as
 buffer overruns and buffer underruns.
 .It 3
-File names and versions of the currently sound loaded modules.
+File names and versions of the currently loaded sound modules.
+.It 4
+Various messages intended for debugging.
 .El
 .It Va hw.snd.maxautovchans
 Global
 .Tn VCHAN
-setting that only affects devices that have only one playback channel.
+setting that only affects devices with only one playback channel available.
 The sound system will dynamically create up this many
 .Tn VCHANs .
 Set to
@@ -223,7 +234,18 @@ Set to
 if no
 .Tn VCHANS
 are desired.
-.It Va hw.snd.pcm%d.vchans
+Maximum value is 255.
+.It Va hw.snd.default_unit
+Default sound card for systems with multiple sound cards.
+When using
+.Xr devfs 5 ,
+the default device for
+.Pa /dev/dsp .
+Equivalent to a symlink from
+.Pa /dev/dsp
+to
+.Pa /dev/dsp Ns Va ${hw.snd.default_unit} .
+.It Va dev.pcm.%d.vchans
 The current number of
 .Tn VCHANs
 allocated per device.
@@ -234,11 +256,23 @@ Setting this value to
 will disable
 .Tn VCHANs
 for this device.
+.It Va dev.pcm.%d.vchanrate
+Sample rate speed for
+.Tn VCHAN
+mixing.
+All playback paths will be converted to this sample rate before the mixing
+process begins.
+.It Va dev.pcm.%d.vchanformat
+Format for
+.Tn VCHAN
+mixing.
+All playback paths will be converted to this format before the mixing
+process begins.
 .El
 .Ss Recording Channels
 On devices that have more than one recording source (ie: mic and line),
 there is a corresponding
-.Pa /dev/dspr%d.%d
+.Pa /dev/dsp%d.r%d
 device.
 .Ss Statistics
 Channel statistics are only kept while the device is open.
@@ -278,8 +312,12 @@ Digitized voice device.
 Like
 .Pa /dev/dsp ,
 but 16 bits per sample.
-.It Pa /dev/dspr%d.%d
-Should be connected to a record codec.
+.It Pa /dev/dsp%d.p%d
+Playback channel.
+.It Pa /dev/dsp%d.r%d
+Record channel.
+.It Pa /dev/dsp%d.v%d
+Virtual channel.
 .It Pa /dev/sndstat
 Current
 .Nm
@@ -301,8 +339,9 @@ device is probed and attached, these messages can be viewed with the
 utility.
 .Sh DIAGNOSTICS
 .Bl -diag
-.It ac97: dac not ready
-AC97 codec is not likely to be accompanied with the sound card.
+.It pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead
+The hardware does not generate interrupts to serve incoming (play)
+or outgoing (record) data.
 .It unsupported subdevice XX
 A device node is not created properly.
 .El
@@ -377,5 +416,5 @@ revised this manual page.
 It was then rewritten for
 .Fx 5.2 .
 .Sh BUGS
-Some features of your cards (e.g., global volume control) might not
+Some features of your sound card (e.g., global volume control) might not
 be supported on all devices.