Add a manual page for the Maestro3 sound driver. This documents it's

special nature under the GPL and a boot hint that can affect operation.

MFC after:	3 days

3 files changed, 151 insertions, 0 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 553bbff..fe2195a 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -74,6 +74,7 @@ MAN=	aac.4 \
 	lp.4 \
 	lpbb.4 \
 	lpt.4 \
+	maestro3.4 \
 	md.4 \
 	mem.4 \
 	mlx.4 \
diff --git a/share/man/man4/maestro3.4 b/share/man/man4/maestro3.4
new file mode 100644
index 0000000..f11b013
--- /dev/null
+++ b/share/man/man4/maestro3.4
@@ -0,0 +1,75 @@
+.\" Copyright (c) 2001 Scott Long
+.\" 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 AUTHOR 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 AUTHOR 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd October 14, 2001
+.Dt MAESTRO3 4
+.Os
+.Sh NAME
+.Nm maestro3
+.Nd FreeBSD audio sub-driver for ESS Maestro3/Allegro-1 hardware
+.Sh SYNOPSIS
+.Dl kldload snd_maestro3
+.Sh DESCRIPTION
+The
+.Nm
+driver provides support for the ESS Maestro3 and Allegro-1 sound chips
+under the PCM framework.
+These chips are mostly found in laptop computers and feature an AC97 mixer,
+a multi-channel sample rate converter that can mix up to four digital audio
+streams in hardware, recording support, and external volume control buttons.
+.Pp
+The firmware for the sound processor is licensed under the GNU Public
+License, and thus this driver is not included in the default GENERIC
+kernel, nor is it compiled into the kernel when
+.Cd "device pcm"
+is specified in the kernel config file.
+A convenient way to automatically load the driver is to add the line
+.Dq Li snd_maestro3=yes
+to the file
+.Pa /boot/loader.conf .
+.Pp
+.Sh DIAGNOSTICS
+The hardware volume control buttons can be connected to two different pin
+sets on the chip, depending on the manufacturer.
+The driver has no way of determining this configuration, so a hint may be
+used to override the default guess.
+Add the line
+.Dq Li hint.pcm.0.hwvol_config="0"
+to the file
+.Pa /boot/device.hints
+to override the default setting.
+.El
+.Sh SEE ALSO
+.Xr pcm 4 ,
+.Xr loader.conf 5
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Fx 4.3 .
+.Sh AUTHORS
+.An Scott Long <scottl@freebsd.org>
+.An Darrel Anderson <anderson@cs.duke.edu>
diff --git a/share/man/man4/snd_maestro3.4 b/share/man/man4/snd_maestro3.4
new file mode 100644
index 0000000..f11b013
--- /dev/null
+++ b/share/man/man4/snd_maestro3.4
@@ -0,0 +1,75 @@
+.\" Copyright (c) 2001 Scott Long
+.\" 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 AUTHOR 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 AUTHOR 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd October 14, 2001
+.Dt MAESTRO3 4
+.Os
+.Sh NAME
+.Nm maestro3
+.Nd FreeBSD audio sub-driver for ESS Maestro3/Allegro-1 hardware
+.Sh SYNOPSIS
+.Dl kldload snd_maestro3
+.Sh DESCRIPTION
+The
+.Nm
+driver provides support for the ESS Maestro3 and Allegro-1 sound chips
+under the PCM framework.
+These chips are mostly found in laptop computers and feature an AC97 mixer,
+a multi-channel sample rate converter that can mix up to four digital audio
+streams in hardware, recording support, and external volume control buttons.
+.Pp
+The firmware for the sound processor is licensed under the GNU Public
+License, and thus this driver is not included in the default GENERIC
+kernel, nor is it compiled into the kernel when
+.Cd "device pcm"
+is specified in the kernel config file.
+A convenient way to automatically load the driver is to add the line
+.Dq Li snd_maestro3=yes
+to the file
+.Pa /boot/loader.conf .
+.Pp
+.Sh DIAGNOSTICS
+The hardware volume control buttons can be connected to two different pin
+sets on the chip, depending on the manufacturer.
+The driver has no way of determining this configuration, so a hint may be
+used to override the default guess.
+Add the line
+.Dq Li hint.pcm.0.hwvol_config="0"
+to the file
+.Pa /boot/device.hints
+to override the default setting.
+.El
+.Sh SEE ALSO
+.Xr pcm 4 ,
+.Xr loader.conf 5
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Fx 4.3 .
+.Sh AUTHORS
+.An Scott Long <scottl@freebsd.org>
+.An Darrel Anderson <anderson@cs.duke.edu>