From ddbf95702a5ab61eda300bd0079d88e3ceb4013b Mon Sep 17 00:00:00 2001
From: Joel Dahl <joel@FreeBSD.org>
Date: Mon, 6 Jul 2009 19:32:13 +0000
Subject: [PATCH] Document the new EQ and VPC features along with a few loader
 tunables.

Reviewed by:	ariff
Approved by:	re (blanket)
---
 share/man/man4/pcm.4 | 61 ++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 56 insertions(+), 5 deletions(-)

diff --git a/share/man/man4/pcm.4 b/share/man/man4/pcm.4
index 5f46444c2435..dbb1437be1f3 100644
--- a/share/man/man4/pcm.4
+++ b/share/man/man4/pcm.4
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 23, 2009
+.Dd July 6, 2009
 .Dt SOUND 4
 .Os
 .Sh NAME
@@ -141,6 +141,15 @@ To define default values for the different mixer channels,
 set the channel to the preferred value using hints, e.g.:
 .Va hint.pcm.0.line Ns = Ns Qq Li 0 .
 This will mute the input channel per default.
+.Ss EQ
+The Parametric Software Equlizer (EQ) enables the use of
+.Dq tone
+controls (bass and treble).
+Commonly used for ear-candy or frequency compensation due to the vast
+difference in hardware quality.
+EQ is disabled by default, but can be enabled with the
+.Va hint.pcm. Ns Ao Ar X Ac Ns Va .eq
+tunable.
 .Ss VCHANs
 Each device can optionally support more playback and recording channels
 than physical hardware provides by using
@@ -151,15 +160,55 @@ or
 options can be configured via the
 .Xr sysctl 8
 interface but can only be manipulated while the device is inactive.
+.Ss VPC
+FreeBSD supports independent and individual volume controls for each active
+application, without touching the master
+.Nm
+volume.
+This is sometimes referred to as Volume Per Channel (VPC).
+The
+.Tn VPC
+feature is enabled by default.
+.Ss Loader Tunables
+The following loader tunables are used to set driver configuration at the
+.Xr loader 8
+prompt before booting the kernel, or they can be stored in
+.Pa /boot/loader.conf
+in order to automatically set them before booting the kernel.
+It is also possible to use
+.Xr kenv 1
+to change these tunables before loading the
+.Nm
+driver.
+The following tunables can not be changed during runtime using
+.Xr sysctl 8 .
+.Bl -tag -width indent
+.It Va hint.pcm. Ns Ao Ar X Ac Ns Va .eq
+Set to 1 or 0 to explicitly enable (1) or disable (0) the equalizer.
+Requires a driver reload if changed.
+Enabling this will make bass and treble controls appear in mixer applications.
+This tunable is undefined by default.
+Equalizing is disabled by default.
+.It Va hint.pcm. Ns Ao Ar X Ac Ns Va .vpc
+Set to 1 or 0 to explicitly enable (1) or disable (0) the
+.Tn VPC
+feature.
+This tunable is undefined by default.
+.Tn VPC
+is however enabled by default.
+.El
 .Ss Runtime Configuration
 There are a number of
 .Xr sysctl 8
-variables available.
+variables available which can be modified during runtime.
+These values can also be stored in
+.Pa /etc/sysctl.conf
+in order to automatically set them during the boot process.
 .Va hw.snd.*
-tunables are global settings and
+are global settings and
 .Va dev.pcm.*
 are device specific.
-.Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent
+.Bl -tag -width indent
 .It Va hw.snd.compat_linux_mmap
 Enable to allow PROT_EXEC page mappings.
 All Linux applications using sound and
@@ -299,7 +348,9 @@ This means that any changes to the volume will be lost.
 Enabling this will preserve the volume, at the cost of possible confusion
 when applications tries to re-open the same device.
 .It Va hw.snd.vpc_mixer_bypass
-The recommended way to use the vpc feature is to teach applications to use
+The recommended way to use the
+.Tn VPC
+feature is to teach applications to use
 the correct
 .Fn ioctl :
 .Dv SNDCTL_DSP_GETPLAYVOL, SNDCTL_DSP_SETPLAYVOL,