From owner-svn-src-all@FreeBSD.ORG Wed Jan 7 16:15:17 2009 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 63093106564A; Wed, 7 Jan 2009 16:15:17 +0000 (UTC) (envelope-from mav@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 4EC308FC12; Wed, 7 Jan 2009 16:15:17 +0000 (UTC) (envelope-from mav@FreeBSD.org) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id n07GFH6q091779; Wed, 7 Jan 2009 16:15:17 GMT (envelope-from mav@svn.freebsd.org) Received: (from mav@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id n07GFHxE091777; Wed, 7 Jan 2009 16:15:17 GMT (envelope-from mav@svn.freebsd.org) Message-Id: <200901071615.n07GFHxE091777@svn.freebsd.org> From: Alexander Motin Date: Wed, 7 Jan 2009 16:15:17 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-7@freebsd.org X-SVN-Group: stable-7 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r186866 - stable/7/share/man/man4 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 07 Jan 2009 16:15:18 -0000 Author: mav Date: Wed Jan 7 16:15:17 2009 New Revision: 186866 URL: http://svn.freebsd.org/changeset/base/186866 Log: Sync snd_hda and snd_ich man pages with CURRENT. Modified: stable/7/share/man/man4/snd_hda.4 stable/7/share/man/man4/snd_ich.4 Modified: stable/7/share/man/man4/snd_hda.4 ============================================================================== --- stable/7/share/man/man4/snd_hda.4 Wed Jan 7 16:06:09 2009 (r186865) +++ stable/7/share/man/man4/snd_hda.4 Wed Jan 7 16:15:17 2009 (r186866) @@ -1,4 +1,5 @@ -.\" Copyright (c) 2006 Joel Dahl +.\" Copyright (c) 2006-2008 Joel Dahl +.\" Copyright (c) 2008 Alexander Motin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -24,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 14, 2007 +.Dd January 7, 2009 .Dt SND_HDA 4 .Os .Sh NAME @@ -45,40 +46,52 @@ 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 +.Nm . +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. +According to HDA and UAA specifications, depending on the number of HDA buses +and codecs present in system, their audio capabilities and BIOS provided +configuration, the +.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. +The assignment of audio inputs and outputs may be tuned with +.Xr device.hints 5 . +The driver's verbose boot messages provide a lot of information about +the operation of the driver and present audio setup. .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. +The default audio device may be tuned by setting the +.Ar hw.snd.default_unit +sysctl, as described in +.Xr sound 4 , +or explicitly specified in application settings. .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 +115,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 +125,145 @@ such as .Dq Li nofixedrate , will do the opposite and takes precedence. Options can be separated by whitespace and commas. +.Dq Li GPIO Ns s +are a codec's 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 have to +experiment a bit with the GPIO setup to find the optimal setup for your +system. +The +.Dq Li ivref Ns Ar X +and +.Dq Li ovref Ns Ar X +options control the voltage used to power external microphones. +.It Va hint.hdac.%d.msi +Controls MSI (Message Signaled Interrupts) support. +.It Va hint.hdac.%d.cad%d.nid%d.config +Overrides codec pin configuration set by BIOS. +May be specified as a 32-bit hexadecimal value with a leading +.Dq 0x , +or as a set of space-separated +.Dq Ar option Ns = Ns Ar 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 the +available codec in alternative ways (for example to get stereo output and 2 +inputs instead of a single 5.1 output). +.Pp +The following options are supported: +.Bl -tag -width ".Va device=" -offset indent +.It Va as +Association number. +Associations are used to group individual pins to form a complex multi-pin +device. +For example, to group 4 connectors for 7.1 output, or to treat several +input connectors as sources for the same input device. +Association numbers can be specified as numeric values from 0 to 15. +A value of 0 means disabled pin. +A value of 15 is a set of independent unassociated pins. +Each association includes only pins of the same direction (in/out) and is +detected atomically (all pins or none). +A separate PCM audio device is created for every pair of input and +output associations. +.It Va seq +Sequence number. +A unique, per-association number used to order pins inside the +particular association. +Sequence numbers can be specified as numeric values from 0 to 15. +.Pp +The sequence number 15 has a special meaning for output associations. +Output pins with this number and device type +.Dq Ar Headphones +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 an input pin, while +.Dq Li Headphones +always means an output. +.It Va conn +Connection type. +Can be specified as a number from 0 to 3. +The connection type can also be specified as one of the special names +.Dq Li Jack , +.Dq Li None , +.Dq Li Fixed , +or +.Dq Li Both . +Pins with a connection type of +.Dq Li None +are disabled. +.It Va ctype +Connector physical type. +Can be specified as a number from 0 to 15. +This is a reference only value. +It is ignored by the +.Nm +driver. +.It Va color +Connector color. +Can be specified as a number from 0 to 15 or as one of the names +.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. +It is ignored by the +.Nm +driver. +.It Va loc +Connector physical location. +Can be specified as a number from 0 to 63. +This is a reference only value. +It is ignored by the +.Nm +driver. +.It Va misc +Misc bits. +Can be specified as a number from 0 to 15. +Bit 0 has a special meaning. When set it means that jack detection is +not implemented in hardware. .El .Ss Runtime Configuration The following @@ -118,19 +271,192 @@ 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. +In this mode 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 EXAMPLES +Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example. +This system has two audio connectors on a front side, three audio connectors +on a rear side and one internal speaker. +According to verbose driver output and the codec datasheet, +this codec has five stereo DACs and two stereo ADCs, all of them are routable to +any codec pin (external connector). +All codec pins are reversible (could be configured either as input or output). +.Pp +So high codec uniformity and flexibility allow driver to configure it in many +different ways, depending on requested pins usage decribed by pins configuration. +Driver reports such default pin configuration when verbose messages enabled: +.Bd -literal +hdac0: nid 20 0x01014020 as 2 seq 0 Line-out Jack jack 1 loc 1 color Green misc 0 +hdac0: nid 21 0x99130110 as 1 seq 0 Speaker Fixed jack 3 loc 25 color Unknown misc 1 +hdac0: nid 22 0x411111f0 as 15 seq 0 Speaker None jack 1 loc 1 color Black misc 1 +hdac0: nid 23 0x411111f0 as 15 seq 0 Speaker None jack 1 loc 1 color Black misc 1 +hdac0: nid 24 0x01a19830 as 3 seq 0 Mic Jack jack 1 loc 1 color Pink misc 8 +hdac0: nid 25 0x02a1983f as 3 seq 15 Mic Jack jack 1 loc 2 color Pink misc 8 +hdac0: nid 26 0x01813031 as 3 seq 1 Line-in Jack jack 1 loc 1 color Blue misc 0 +hdac0: nid 27 0x0221401f as 1 seq 15 Headphones Jack jack 1 loc 2 color Green misc 0 +hdac0: nid 28 0x411111f0 as 15 seq 0 Speaker None jack 1 loc 1 color Black misc 1 +hdac0: nid 30 0x411111f0 as 15 seq 0 Speaker None jack 1 loc 1 color Black misc 1 +hdac0: nid 31 0x411111f0 as 15 seq 0 Speaker None jack 1 loc 1 color Black misc 1 +.Ed +.Pp +Here we can see, that the nodes with ID (nid) 25 and 27 are front pannel +connectors (Jack, loc 2), nids 20, 24 and 26 are rear pannel connectors +(Jack, loc 1) and nid 21 is a built-in speaker (Fixed, loc 25). +Pins with nids 22, 23, 28, 30 and 31 will be disabled by driver due to "None" +connectivity. So the pin count and description matches to connectors that +we have. +.Pp +Using association (as) and sequence (seq) fields values pins are grouped into +3 associations: +.Bd -literal +hdac0: Association 0 (1) out: +hdac0: Pin nid=21 seq=0 +hdac0: Pin nid=27 seq=15 +hdac0: Association 1 (2) out: +hdac0: Pin nid=20 seq=0 +hdac0: Association 2 (3) in: +hdac0: Pin nid=24 seq=0 +hdac0: Pin nid=26 seq=1 +hdac0: Pin nid=25 seq=15 +.Ed +.Pp +Each +.Xr pcm 4 +device uses two associations: one for playback and one for recording. +Associations processed and assigned to +.Xr pcm 4 +devices in increasing numerical order. +In this case association #0 (1) will become +.Li pcm0 +device playback, using the internal speakers and +.Ar Headphones +jack with speaker automute on the headphones jack connection. +Association #1 (2) will become +.Li pcm1 +playback, using the +.Ar Line-out +jack. +Association #2 (3) will become +.Li pcm0 +recording, using the external microphones and the +.Ar Line-in +jack. +.Pp +The +.Nm +driver provides extensive verbose messages to diagnose its operation +logic and describe its current codec configuration. +.Pp +Using +.Xr device.hints 5 +it is possible to modify the configuration of the existing pins, +allowing a broad range of different audio setups. +Here are a few examples of some setups possible for this particular +hardware: +.Ss Example 1 +Setting the +.Xr device.hints 5 +options +.Bd -literal +hint.hdac.0.cad0.nid20.config="as=1" +hint.hdac.0.cad0.nid21.config="as=2" +.Ed +.Pp +will swap line-out and speaker functions. +So the +.Li pcm0 +device will play to the line-out and headphones jacks. Line-out will +be muted on the headphones jack connection. +Recording on +.Li pcm0 +will go from two external microphones and line-in jacks. +.Li pcm1 +playback will go to the internal speaker. +.Pp +.Ss Example 2 +Setting the +.Xr device.hints 5 +options +.Bd -literal +hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones" +hint.hdac.0.cad0.nid27.config="as=2 seq=0" +hint.hdac.0.cad0.nid25.config="as=4 seq=0" +.Ed +.Pp +will split the headphones and one of the microphones to a separate device. +The +.Li pcm0 +device will play to the internal speaker and to the line-out jack, with +speaker automute on the line-out jack connection. +Recording on +.Li pcm0 +will use input from one external microphone and the line-in jacks. +The +.Li pcm1 +device will be completely dedicated to a headset (headphones and mic) +connected to the front connectors. +.Pp +.Ss Example 3 +Setting the +.Xr device.hints 5 +options +.Bd -literal +hint.hdac.0.cad0.nid20.config="as=1 seq=0" +hint.hdac.0.cad0.nid26.config="as=2 seq=0" +hint.hdac.0.cad0.nid27.config="as=3 seq=0" +hint.hdac.0.cad0.nid25.config="as=4 seq=0" +hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out" +hint.hdac.0.cad0.nid21.config="as=6 seq=0" +.Ed +.Pp +will give 4 independent devices: +.Li pcm0 +.Pq line-out and line-in , +.Li pcm1 +.Pq headphones and mic , +.Li pcm2 +.Pq additional line-out via retasked rear mic jack , +and +.Li pcm3 +.Pq internal speaker . +.Pp +.Ss Example 4 +Setting the +.Xr device.hints 5 +options +.Bd -literal +hint.hdac.0.cad0.nid20.config="as=1 seq=0" +hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out" +hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out" +hint.hdac.0.cad0.nid21.config="as=2 seq=0" +.Ed +.Pp +will give 2 devices: +.Li pcm0 +for 5.1 playback via 3 rear connectors (line-out and retasked +mic and line-in) and headset (headphones and mic) at front connectors. +.Li pcm1 +for internal speaker playback. +On headphones connection rear connectors will be muted. .Sh HARDWARE The .Nm -driver supports the following audio chipsets: +driver supports many Intel HDA compatible audio chipsets including the +following: .Pp .Bl -bullet -compact .It @@ -140,13 +466,17 @@ ATI SB600 .It Intel 631x/632xESB .It -Intel 82801F +Intel 82801F (ICH6) +.It +Intel 82801G (ICH7) .It -Intel 82801G +Intel 82801H (ICH8) .It -Intel 82801H +Intel 82801I (ICH9) .It -Intel 82801I +Intel 82801J (ICH10) +.It +Intel US15W (SCH) .It nVidia MCP51 .It @@ -156,18 +486,26 @@ nVidia MCP61A .It nVidia MCP61B .It +nVidia MCP63 +.It nVidia MCP65A .It nVidia MCP65B .It +nVidia MCP67A +.It +nVidia MCP67B +.It +nVidia MCP68 +.It +nVidia MCP69 +.It SiS 966 .It VIA VT8251/8237A .El .Pp -Generic audio chipsets compatible with the Intel HDA specification should work, -but have not been verified yet. -The following codecs have been verified to work: +The following and many other codecs have been verified to work: .Pp .Bl -bullet -compact .It @@ -175,6 +513,8 @@ Analog Devices AD1981HD .It Analog Devices AD1983 .It +Analog Devices AD1984 +.It Analog Devices AD1986A .It Analog Devices AD1988 @@ -183,9 +523,11 @@ Analog Devices AD1988B .It CMedia CMI9880 .It -Conexant Venice +Conexant CX20549 (Venice) .It -Conexant Waikiki +Conexant CX20551 (Waikiki) +.It +Conexant CX20561 (Hermosa) .It Realtek ALC260 .It @@ -209,24 +551,47 @@ Realtek ALC885 .It Realtek ALC888 .It +Realtek ALC889 +.It +Sigmatel STAC9205 +.It Sigmatel STAC9220 .It -Sigmatel STAC9220D/9223D +Sigmatel STAC9220D / 9223D .It Sigmatel STAC9221 .It Sigmatel STAC9221D .It -Sigmatel STAC9227 +Sigmatel STAC9227D +.It +Sigmatel STAC9227X +.It +Sigmatel STAC9228D +.It +Sigmatel STAC9228X +.It +Sigmatel STAC9229D +.It +Sigmatel STAC9229X +.It +Sigmatel STAC9230D +.It +Sigmatel STAC9230X .It Sigmatel STAC9271D .It +Sigmatel STAC9872AK +.It VIA VT1708 .It +VIA VT1708B +.It VIA VT1709 .El .Sh SEE ALSO .Xr sound 4 , +.Xr snd_ich 4 , .Xr device.hints 5 , .Xr loader.conf 5 , .Xr sysctl 8 @@ -240,18 +605,26 @@ 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 , +.An Alexander Motin Aq mav@FreeBSD.org +and +.An Giorgos Keramidas Aq keramida@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 driver useless, which usually results in a state where the .Nm -driver seems to attach and work, but without any sound. +driver seems to attach and work, but without any sound. Some of +that cases can be solved by tuning loader.conf variables. But before +trying to fix problem that way, make sure that problem is really exists +and the PCM audio device you are using really corresponds to expected +audio connector. +.Pp +Due to OSS limitation multichannel (not multidevice) playback is not +supported. Modified: stable/7/share/man/man4/snd_ich.4 ============================================================================== --- stable/7/share/man/man4/snd_ich.4 Wed Jan 7 16:06:09 2009 (r186865) +++ stable/7/share/man/man4/snd_ich.4 Wed Jan 7 16:15:17 2009 (r186866) @@ -24,12 +24,12 @@ .\" .\" $FreeBSD$ .\" -.Dd December 15, 2005 +.Dd January 6, 2009 .Dt SND_ICH 4 .Os .Sh NAME .Nm snd_ich -.Nd "Intel ICH PCI and compatible bridge device driver" +.Nd "Intel ICH AC'97 and compatible bridge device driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: @@ -49,7 +49,12 @@ The .Nm bridge driver allows the generic audio driver .Xr sound 4 -to attach to Intel ICH and compatible audio devices. +to attach to Intel ICH AC'97 and compatible audio devices. +.Pp +Some later chips, like ICH6/ICH7, depending on wiring can instead implement +newer Intel HD Audio specification, which is supported by +.Xr snd_hda 4 +driver. .Sh HARDWARE The .Nm @@ -94,7 +99,8 @@ NVIDIA nForce4 SiS 7012 .El .Sh SEE ALSO -.Xr sound 4 +.Xr sound 4 , +.Xr snd_hda 4 .Sh HISTORY The .Nm