Update man page according to r182999 snd_hda driver update.

1 files changed, 160 insertions, 33 deletions

diff --git a/share/man/man4/snd_hda.4 b/share/man/man4/snd_hda.4
index 831f709..d7f650a 100644
--- a/share/man/man4/snd_hda.4
+++ b/share/man/man4/snd_hda.4
@@ -1,4 +1,5 @@
-.\" Copyright (c) 2006 Joel Dahl <joel@FreeBSD.org>
+.\" Copyright (c) 2006-2008 Joel Dahl <joel@FreeBSD.org>
+.\" Copyright (c) 2008 Alexander Motin <mav@FreeBSD.org>
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -24,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 11, 2008
+.Dd Sep 11, 2008
 .Dt SND_HDA 4
 .Os
 .Sh NAME
@@ -45,40 +46,43 @@ following line in
 snd_hda_load="YES"
 .Ed
 .Sh DESCRIPTION
+The High Definition (HD) Audio specification was developed by Intel as the
+logical successor of the old AC'97 specification and has several advantages,
+such as higher bandwidth which allows more channels and more detailed formats,
+support for several logical audio devices, and general purpose DMA channels.
+.Pp
 The
 .Nm
-bridge device driver allows the generic audio driver,
+driver is a HDA bus controller driver and HDA codecs audio functions bridge
+driver that allows the generic audio driver,
 .Xr sound 4 ,
-to attach to Intel High Definition Audio devices.
+to be used with this hardware.
+Only audio functions are supported by this driver. Modem, HDMI and other
+possible functions are not implemented.
+.Pp
 The
 .Nm
 driver supports hardware that conforms with revision 1.0 of the Intel High
 Definition Audio specification and tries to behave much like the Microsoft
 Universal Audio Architecture (UAA) draft (revision 0.7b) for handling audio
 devices.
-HDA acts like a primary bus, similar to
-.Xr miibus 4 ,
-for handling various child buses such as audio, modem and HDMI (High Definition
-Multimedia Interface).
-Only audio is implemented in the
-.Nm
-driver.
 .Pp
-The High Definition (HD) Audio specification was developed by Intel as the
-logical successor of the old AC'97 specification and has several advantages,
-such as higher bandwidth which allows more channels and more detailed formats,
-support for several logical audio devices, and general purpose DMA channels.
-.Pp
-The HDA specification defines the register-level interface, physical link
-characteristics, codec programming models, and codec architectural components.
-This specification is intended for both device driver developers and hardware
-component designers.
+According to HDA and UAA specifications, depending on number of HDA buses
+and codecs present in system, their audio capabilities and BIOS provided
+configuration,
+.Nm
+driver often provides several PCM audio devices. For example, one device for
+main rear 7.1 output and inputs, one device for independent headset connectors
+at front and one device for SPDIF or HDMI audio input/output. Usually that
+assignment may be widely tuned by user using device hints. A lot of useful
+information about driver operation and present audio setup may be obtained from
+the driver verbose boot messages.
 .Ss Boot-time Configuration
 The following variables are available at boot-time through the
 .Xr device.hints 5
 file:
-.Bl -tag -width ".Va hint.pcm.%d.config" -offset indent
-.It Va hint.pcm.%d.config
+.Bl -tag -width ".Va hint.hdac.%d.config"-offset indent
+.It Va hint.hdac.%d.config
 Configures a range of possible options.
 Possible values are:
 .Dq Li dmapos ,
@@ -102,6 +106,7 @@ Possible values are:
 .Dq Li ovref50 ,
 .Dq Li ovref80 ,
 .Dq Li ovref100 ,
+.Dq Li senseinv ,
 .Dq Li softpcmvol ,
 and
 .Dq Li vref .
@@ -111,6 +116,122 @@ such as
 .Dq Li nofixedrate ,
 will do the opposite and takes precedence.
 Options can be separated by whitespace and commas.
+GPIO is a codecs General Purpose I/O pins which system integrators sometimes
+use to control external muters, amplifiers and so on.
+If you have no sound or sound volume is not adequate you may need to find a
+GPIO combination required for your system.
+ivrefX/ovrefX options controls voltage used to power external microphones
+and so on.
+.It Va hint.hdac.%d.cad%d.nid%d.config
+Overrides codec pin configuration set by BIOS.
+May be specified as a 32bit HEX value with a leading "0x" or as a set of
+space separated "option=value" pairs.
+.El
+.Pp
+Pin configuration is the UAA driver's main source of information about codec
+usage.
+This information is usually provided by the codec manufacturer and tuned
+by system integrators for specific system requirements.
+The
+.Nm
+driver allows users to override it to fix integrator mistakes or to use codec
+in alternative ways, for example, to get stereo output and 2 inputs
+instead of a single 5.1 output.
+Configuration includes the following options:
+.Bl -tag -width ".Va device=" -offset indent
+.It Va as
+Association number.
+Associations are used to group individual pins to form a complex multipin
+device.
+For example, to group 4 connectors for 7.1 output or to treat several
+input connectors as sources for the same input device.
+Can be specified as number from 0 to 15.
+Association number 0 means disabled pin, number 15 is a set of independent
+unassociated pins.
+Each association includes only pins of the same direction (in/out) and
+detected atomically - all pins or none.
+For every pair of input+output associations in order of their numeration
+separate PCM audio device is created.
+.It Va seq
+Sequence number.
+This unique inside every association number used to order pins inside
+association.
+Can be specified as a number from 0 to 15.
+Sequence number 15 for output associations has also special meaning.
+Output pin with sequence number 15 and device type Headhones will duplicate
+(with automatic mute if jack detection is supported) the first pin in that
+association.
+.It Va device
+Device type.
+Can be specified as a number from 0 to 15 or as a name:
+.Dq Li Line-out ,
+.Dq Li Speaker ,
+.Dq Li Headphones,
+.Dq Li CD ,
+.Dq Li SPDIF-out ,
+.Dq Li Digital-out ,
+.Dq Li Modem-line ,
+.Dq Li Modem-handset ,
+.Dq Li Line-in ,
+.Dq Li AUX ,
+.Dq Li Mic ,
+.Dq Li Telephony ,
+.Dq Li SPDIF-in ,
+.Dq Li Digital-in ,
+.Dq Li Res.E ,
+or
+.Dq Li Other .
+The device type also describes the pin direction (in/out).
+For example,
+.Dq Li CD
+always means input pin, while
+.Dq Li Headphones
+always means  output.
+.It Va conn
+Connection type.
+Can be specified as a number from 0 to 3 or as a name:
+.Dq Li Jack ,
+.Dq Li None ,
+.Dq Li Fixed ,
+or
+.Dq Li Both .
+Pins with
+.Dq Li None
+connection type are disabled.
+.It Va ctype
+Connector physical type.
+Can be specified as a number from 0 to 15.
+This is a reference only value which is ignored by the driver.
+.It Va color
+Connector color.
+Can be specified as a number from 0 to 15 or as a name:
+.Dq Li Unknown ,
+.Dq Li Black ,
+.Dq Li Grey ,
+.Dq Li Blue ,
+.Dq Li Green ,
+.Dq Li Red ,
+.Dq Li Orange ,
+.Dq Li Yellow ,
+.Dq Li Purple ,
+.Dq Li Pink ,
+.Dq Li Res.A ,
+.Dq Li Res.B ,
+.Dq Li Res.C ,
+.Dq Li Res.D ,
+.Dq Li White ,
+or
+.Dq Li Other .
+This is a reference only value which is ignored by the driver.
+.It Va loc
+Connector physical location.
+Can be specified as a number from 0 to 63.
+This is a reference only value which is ignored by the driver.
+.It Va misc
+Misc bits.
+Can be specified as a number from 0 to 15.
+Bit 0, if set, tells that jack detection on this pin supported by the codec
+is not implemented in hardware.
 .El
 .Ss Runtime Configuration
 The following
@@ -118,14 +239,20 @@ The following
 variables are available in addition to those available to all
 .Xr sound 4
 devices:
-.Bl -tag -width ".Va dev.pcm.%d.polling" -offset indent
-.It Va dev.pcm.%d.polling
-Experimental polling mode, where the driver operates by querying the device
-state on each tick using
-.Xr callout 9 .
+.Bl -tag -width ".Va dev.hdac.%d.polling" -offset indent
+.It Va dev.hdac.%d.polling
+Enables polling mode, where the driver operates by querying the device
+state on timer ticks using
+.Xr callout 9
+instead of interrupts.
 Polling is disabled by default.
 Do not enable it unless you are facing weird interrupt problems or if the
 device cannot generate interrupts at all.
+.It Va dev.hdac.%d.polling_interval
+Controller/Jack Sense polling interval (1-1000 ms)
+.It Va dev.hdac.%d.pindump
+Setting this to a non-zero value dumps the current pin configuration, main
+capabilities and jack sense status to console and syslog.
 .El
 .Sh HARDWARE
 The
@@ -248,15 +375,15 @@ device driver first appeared in
 The
 .Nm
 driver was written by
-.An Stephane E. Potvin Aq sepotvin@videotron.ca
+.An Stephane E. Potvin Aq sepotvin@videotron.ca ,
+.An Ariff Abdullah Aq ariff@FreeBSD.org
 and
-.An Ariff Abdullah Aq ariff@FreeBSD.org .
+.An Alexander Motin Aq mav@FreeBSD.org .
 This manual page was written by
-.An Joel Dahl Aq joel@FreeBSD.org .
+.An Joel Dahl Aq joel@FreeBSD.org
+and
+.An Alexander Motin Aq mav@FreeBSD.org .
 .Sh BUGS
-There are a couple of missing features, such as support for Digital
-S/PDIF and multichannel output.
-.Pp
 A few Hardware/OEM vendors tend to screw up BIOS settings, thus
 rendering the
 .Nm