describe a bit more about High Definition Audio architecture

as well as how the mixer item names are derived.

1 files changed, 227 insertions, 7 deletions

diff --git a/share/man/man4/azalia.4 b/share/man/man4/azalia.4
index 3ad7f4c370b..aea250aee33 100644
--- a/share/man/man4/azalia.4
+++ b/share/man/man4/azalia.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: azalia.4,v 1.21 2009/08/02 09:28:06 sthen Exp $
+.\"	$OpenBSD: azalia.4,v 1.22 2009/10/20 06:31:26 jakemsr Exp $
 .\"	$NetBSD: azalia.4,v 1.2 2005/06/22 04:19:09 kent Exp $
 .\"
 .\" Copyright (c) 2005 The NetBSD Foundation, Inc.
@@ -28,7 +28,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 2 2009 $
+.Dd $Mdocdate: October 20 2009 $
 .Dt AZALIA 4
 .Os
 .Sh NAME
@@ -43,7 +43,7 @@ The
 device driver is expected to support any PCI device which is
 compliant with the High Definition Audio Specification 1.0.
 .Pp
-Supported chipsets:
+Supported controllers include:
 .Pp
 .Bl -bullet -compact -offset indent
 .It
@@ -59,6 +59,228 @@ Silicon Integrated System 966/966L
 .It
 VIA Technologies VT8237A, VT8251
 .El
+.Pp
+The High Definition Audio (HDA) specification describes a flexible and
+extensible infrastructure to support high quality audio.
+HDA supports sample rates up to 192 kHz, bit rates of up to 32 bits per
+sample, and up to 16 channels in audio streams.
+It also supports S/PDIF input/output as well as jack retasking and sensing.
+The HDA specification defines a controller register set and a codec
+architecture.
+.Sh MIXER INTERFACE
+The codec is the main audio processor.
+Configuration of the device, such as selecting playback sample rate
+or decreasing the volume, is handled by the codec.
+Codecs are comprised of interconnected widgets.
+Common examples of widgets include DACs (digital to analog converter),
+ADCs (analog to digital converter), selectors, mixers, and pin
+complexes (input/output jacks).
+Widgets may have fixed or controllable properties.
+Some of these properties include source selection, amplifier gain,
+mute, and operational direction.
+.Pp
+The mixer interface for
+.Nm
+is designed to allow the user to control most properties of the widgets.
+When
+.Nm
+first attaches and configures the device, it will set all widgets to
+unmuted, moderate volume, and configure connections such that stereo
+playback and recording will work with the expected input/output pins.
+.Pp
+There are a wide range of HDA codecs.
+Some have only a few widgets that don't have many controllable
+properties, and some may have many, very controllable widgets.
+The mixer interface on one
+.Nm
+may be very different than the mixer interface on another.
+.Pp
+Mixer item names describe the widget and property being controlled.
+Names take the following form:
+.Bd -literal
+<mixer class>.<widget type>[<widget type enumerator>][_<property>]
+.Ed
+.Pp
+The mixer class gives a hint as to the purpose of the control.
+The widget type enumerator is used to distinguish different widgets
+of the same type.
+The enumeration starts at 2: the first widget of each type is not
+enumerated.
+Except for dac and adc widget types, the enumeration order is
+meaningless.
+The property is optional.
+Generally, if there is no property, the mixer item is an amplifier gain
+control.
+.Pp
+The following are the widget type names used in mixer control names:
+.Pp
+.Bl -tag -width "SPDIF-in"
+.It Cm dac
+Digital to analog converter, usually used for playback.
+These widgets are enumerated according to the channels they convert.
+For example, if a codec has 3 stereo dacs, they would convert the
+following channels: dac channels 0 and 1, dac2 channels 2 and 3,
+dac3 channels 4 and 5.
+.Pp
+.It Cm dig-dac
+Digital output converter, usually an S/PDIF transmitter.
+.Pp
+.It Cm adc
+Analog to digital converter, usually used for recording.
+These widgets are enumerated according to the channels they convert.
+For example, if a codec has 2 stereo adcs, they would convert the
+following channels: adc channels 0 and 1, adc2 channels 2 and 3.
+.Pp
+.It Cm dig-adc
+Digital input converter, usually an S/PDIF receiver.
+.Pp
+.It Cm mix
+Sums multiple audio sources into a single stream, but
+sometimes only used for amplifier or mute properties.
+The property part of a mix widget mixer control name may be
+the name of another widget.
+Such a mixer item controls the input level from the widget in the
+property part of the name.
+.Pp
+.It Cm sel
+Selects a single audio source, but sometimes used only for amplifier
+or mute properties.
+.Pp
+.It Cm pow
+Controls power state for a group of widgets.
+.Pp
+.It Cm volume
+Interprets data from external controls, such as a volume knob.
+.Pp
+.It Cm beep
+Creates a tone at a certain frequency.
+.Pp
+.It Cm line
+Pin complex for a line-level jack that is normally used for analog audio
+output.
+The name may also be appended with a color abbreviation such as -grn (green),
+-blk (black), -org (orange), or -gry (grey), to help differentiate jacks.
+.Pp
+.It Cm spkr
+Pin complex for a speaker, often built into the machine.
+.Pp
+.It Cm hp
+Pin complex for a jack that is normally used for output to a headphone.
+.Pp
+.It Cm cd
+Pin complex for analog audio input from a CD device.
+.Pp
+.It Cm SPDIF
+Pin complex for an S/PDIF output connector.
+.Pp
+.It Cm line-in
+Pin complex for a line-level jack that is normally used for analog audio input.
+.Pp
+.It Cm aux
+Pin complex for an auxiliary analog audio input.
+.Pp
+.It Cm mic
+Pin complex for analog audio input from a microphone, either a jack or built
+into the machine.
+.Pp
+.It Cm SPDIF-in
+Pin complex for an S/PDIF input connector.
+.Pp
+.It Cm beep
+Pin complex for analog audio input from a beep generator.
+.El
+.Pp
+The following are the property names used in mixer control names:
+.Pp
+.Bl -tag -width "source"
+.It Cm mute
+Mutes input or output audio stream.
+.Pp
+.It Cm source
+Selects input source.
+Can either select a single source or multiple sources.
+Sometimes these controls may only have a single choice, but they are
+provided to show how audio streams move through the codec.
+.Pp
+.It Cm dir
+Selects pin direction and input VRef signal.
+VRef is represented in percent of the analog voltage rail.
+For example, 'input-vr80' means input direction with 80% VRef.
+.Pp
+.It Cm boost
+Enables/disables low impedence amplifier, usually for use with headphones.
+.Pp
+.It Cm eapd
+Powers on/off external amplifier circuitry.
+.Pp
+.It Cm sense
+Reports current jack sense state.
+.El
+.Pp
+There are also some special mixer controls that don't directly
+correspond to properties of the widgets, but control aspects
+of the driver or other mixer controls.
+The following describes these special controls:
+.Bl -tag -width "outputsXmasterXslaves"
+.It Cm outputs.spkr_muters
+List of pins that can mute a built-in speaker.
+A pin mutes the speaker by sending a signal when it senses that something
+has been plugged into its jack.
+If a pin supports both input and output operation, the pin will only mute
+the speaker when plugged into if that pin is configured for output.
+.Pp
+.It Cm outputs.master.slaves
+List of widgets with amplifier gain or mute controls that are configured
+with the parameters used for
+.Cm outputs.master
+and
+.Cm outputs.master.mute .
+For example, if
+.Cm dac
+is in the list and has an input amplifier gain control, setting
+.Cm outputs.master
+to 200 will set
+.Cm inputs.dac
+to 200.
+.Pp
+.It Cm outputs.master
+Amplifier gain control for widgets listed in
+.Cm outputs.master.slaves .
+.Pp
+.It Cm outputs.master.mute
+Mute control for widgets listed in
+.Cm outputs.master.slaves .
+.Pp
+.It Cm record.volume.slaves
+List of widgets with amplifier gain or mute controls that are configured
+with the parameters used for
+.Cm record.volume
+and
+.Cm record.volume.mute .
+For example, if
+.Cm adc
+is in the list and has an input amplifier gain control, setting
+.Cm record.volume
+to 200 will set
+.Cm record.adc
+to 200.
+.Pp
+.It Cm record.volume
+Amplifier gain control for widgets listed in
+.Cm record.volume.slaves .
+.Pp
+.It Cm record.volume.mute
+Mute control for widgets listed in
+.Cm record.volume.slaves .
+.Pp
+.It Cm outputs.mode
+Controls whether the digital or analog converters and pins will be
+used for playback.
+.Pp
+.It Cm record.mode
+Controls whether the digital or analog converters and pins will be
+used for recording.
+.El
 .Sh SEE ALSO
 .Xr audio 4 ,
 .Xr pci 4
@@ -71,7 +293,5 @@ device driver first appeared in
 support first appeared in
 .Ox 4.0 .
 .Sh BUGS
-Non-PCM encodings such as Float32 and AC-3 are not supported.
-.Pp
-There is no way to use 20-bit or 24-bit precision because of a
-limitation of the MI audio framework.
+This driver does not support codecs that are intended for HDMI or
+DisplayPort connectivity.