NetBSD/share/man/man4/hdaudio.4

.\"	$NetBSD: hdaudio.4,v 1.14 2014/09/19 17:27:12 christos Exp $
.\"
.\" Copyright (c) 2009, 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Precedence Technologies Ltd
.\"
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.\"
.Dd September 19, 2014
.Dt HDAUDIO 4
.Os
.Sh NAME
.Nm hdaudio
.Nd High Definition Audio device driver
.Sh SYNOPSIS
.Cd "hdaudio* at pci? dev ? function ?"
.Cd "hdafg* at hdaudiobus?"
.Cd "audio* at audiobus?"
.Pp
.Cd "options HDAUDIOVERBOSE"
.Cd "options HDAUDIO_DEBUG"
.Cd "options HDAFG_DEBUG"
.Sh DESCRIPTION
The
.Nm
device driver is expected to support any PCI device which is
compliant to the High Definition Audio Specification 1.0.
It is a replacement for
.Xr azalia 4 .
It was written from scratch following the Intel HD Audio and Microsoft
Universal Audio Architecture specifications.
.Pp
The driver consists of two interlinked components, which reflects the
hardware design.
The
.Nm
component interfaces with a PCI/PCIe bus and provides an
.Xr hdaudiobus 4
onto which different function groups attach.
Each function group (e.g. audio, vendor-specific modem) is exported as a
separate child device of the
.Nm
controller.
Audio function groups (a.k.a. audio codec) are exported as
.Xr hdafg 4
devices.
.Pp
Audio codecs are available from a number of manufacturers and are made up of a
number of widgets (e.g. audio mixer, output pin, analog-to-digital converter).
The way the widgets are interlinked varies significantly between
implementations.
The tree of widgets must be parsed and mapped to
.Xr mixer 4
controls.
As part of this process, loops in the inter-codec links must be detected
and muted, bi-directional pins must be set up appropriately and the locations
of pins determined.
Unlike the
.Xr azalia 4
driver (which tends to generate a large number of unclearly named
.Xr mixer 4
controls),
.Nm
works backwards by starting with a list of desired, consistent and compatible
.Xr mixer 4
controls and configuring/discovering appropriate widget link routes to fit.
.Pp
By following the published mechanisms for common implementations of widget
parsing, it is expected that nearly all High Definition Audio devices will
be supported without requiring per-device quirks.
.Sh HARDWARE
In addition to many on-board sound cards included in mainboards, the following
add-on card is supported:
.Bl -tag
.It TerraTec Aureon 7.1 PCIe
.El
.Sh SEE ALSO
.Xr audio 4 ,
.Xr mixer 4 ,
.Xr pci 4 ,
.Xr hdaudioctl 8 ,
.Pp
.Lk http://www.intel.com/design/chipsets/hdaudio.htm "Intel High Definition Audio"
.Pp
.Lk http://www.microsoft.com/whdc/device/audio/ "Audio Device Technologies for Windows"
.Sh HISTORY
The
.Nm
device driver appeared in
.Nx 5.1 .
.Sh AUTHORS
The
.Nm
driver was written by
.An Jared McNeill Aq Mt jmcneill@NetBSD.org
under contract by
.Lk http://www.precedence.co.uk/ "Precedence Technologies Ltd."
The UAA-compliant widget parser is derived from the
.Fx
snd_hda(4) driver.
.Sh BUGS
The following items are not yet implemented:
.Bl -bullet
.It
Improve power management support when driver is idle
.It
Add support for non-PCM output formats
.It
Handle unsolicited RIRB messages
.It
Modem function groups
.El
document verbose 2014-09-19 21:27:12 +04:00			`.\" $NetBSD: hdaudio.4,v 1.14 2014/09/19 17:27:12 christos Exp $`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`.\"`
hdaudio appeared in 5.1. Add xref to hdaudioctl(8). From rudolf. Bump date. 2010-09-28 16:25:27 +04:00			`.\" Copyright (c) 2009, 2010 The NetBSD Foundation, Inc.`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`.\" All rights reserved.`
			`.\"`
			`.\" This code is derived from software contributed to The NetBSD Foundation`
			`.\" by Precedence Technologies Ltd`
			`.\"`
			`.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.`
			`.\"`
document verbose 2014-09-19 21:27:12 +04:00			`.Dd September 19, 2014`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`.Dt HDAUDIO 4`
			`.Os`
			`.Sh NAME`
			`.Nm hdaudio`
- adjust description ("Generic" is redundant) - rates != 48kHz are now supported - bump date 2009-09-07 20:22:46 +04:00			`.Nd High Definition Audio device driver`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`.Sh SYNOPSIS`
			`.Cd "hdaudio* at pci? dev ? function ?"`
			`.Cd "hdafg* at hdaudiobus?"`
			`.Cd "audio* at audiobus?"`
			`.Pp`
document verbose 2014-09-19 21:27:12 +04:00			`.Cd "options HDAUDIOVERBOSE"`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`.Cd "options HDAUDIO_DEBUG"`
Correct option name for hdaudio debugging. Reported by Dave Tyson in PR 46357. 2012-04-20 00:20:34 +04:00			`.Cd "options HDAFG_DEBUG"`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`.Sh DESCRIPTION`
			`The`
			`.Nm`
			`device driver is expected to support any PCI device which is`
			`compliant to the High Definition Audio Specification 1.0.`
			`It is a replacement for`
			`.Xr azalia 4 .`
			`It was written from scratch following the Intel HD Audio and Microsoft`
			`Universal Audio Architecture specifications.`
Whitespace cleanup, sort sections, fix list. 2009-09-06 21:59:09 +04:00			`.Pp`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`The driver consists of two interlinked components, which reflects the`
			`hardware design.`
			`The`
			`.Nm`
			`component interfaces with a PCI/PCIe bus and provides an`
			`.Xr hdaudiobus 4`
			`onto which different function groups attach.`
Whitespace cleanup, sort sections, fix list. 2009-09-06 21:59:09 +04:00			`Each function group (e.g. audio, vendor-specific modem) is exported as a`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`separate child device of the`
			`.Nm`
			`controller.`
Whitespace cleanup, sort sections, fix list. 2009-09-06 21:59:09 +04:00			`Audio function groups (a.k.a. audio codec) are exported as`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`.Xr hdafg 4`
			`devices.`
Whitespace cleanup, sort sections, fix list. 2009-09-06 21:59:09 +04:00			`.Pp`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`Audio codecs are available from a number of manufacturers and are made up of a`
			`number of widgets (e.g. audio mixer, output pin, analog-to-digital converter).`
			`The way the widgets are interlinked varies significantly between`
			`implementations.`
			`The tree of widgets must be parsed and mapped to`
			`.Xr mixer 4`
			`controls.`
			`As part of this process, loops in the inter-codec links must be detected`
			`and muted, bi-directional pins must be set up appropriately and the locations`
			`of pins determined.`
			`Unlike the`
			`.Xr azalia 4`
			`driver (which tends to generate a large number of unclearly named`
			`.Xr mixer 4`
Whitespace cleanup, sort sections, fix list. 2009-09-06 21:59:09 +04:00			`controls),`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`.Nm`
			`works backwards by starting with a list of desired, consistent and compatible`
			`.Xr mixer 4`
			`controls and configuring/discovering appropriate widget link routes to fit.`
Whitespace cleanup, sort sections, fix list. 2009-09-06 21:59:09 +04:00			`.Pp`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`By following the published mechanisms for common implementations of widget`
			`parsing, it is expected that nearly all High Definition Audio devices will`
			`be supported without requiring per-device quirks.`
Mention that TerraTec Aureon 7.1 PCIe is supported by this driver. Bump date. 2013-05-10 15:05:14 +04:00			`.Sh HARDWARE`
Improve wording. 2013-08-06 20:54:46 +04:00			`In addition to many on-board sound cards included in mainboards, the following`
Mention that TerraTec Aureon 7.1 PCIe is supported by this driver. Bump date. 2013-05-10 15:05:14 +04:00			`add-on card is supported:`
			`.Bl -tag`
			`.It TerraTec Aureon 7.1 PCIe`
			`.El`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`.Sh SEE ALSO`
			`.Xr audio 4 ,`
			`.Xr mixer 4 ,`
			`.Xr pci 4 ,`
hdaudio appeared in 5.1. Add xref to hdaudioctl(8). From rudolf. Bump date. 2010-09-28 16:25:27 +04:00			`.Xr hdaudioctl 8 ,`
Use Lk macro instead of Pa when dealing with URLs, to produce links with HTML output. And while here update or removed some dead URL links. Another part of PR/29238. 2012-03-13 23:25:39 +04:00			`.Pp`
			`.Lk http://www.intel.com/design/chipsets/hdaudio.htm "Intel High Definition Audio"`
			`.Pp`
			`.Lk http://www.microsoft.com/whdc/device/audio/ "Audio Device Technologies for Windows"`
Whitespace cleanup, sort sections, fix list. 2009-09-06 21:59:09 +04:00			`.Sh HISTORY`
			`The`
			`.Nm`
			`device driver appeared in`
hdaudio appeared in 5.1. Add xref to hdaudioctl(8). From rudolf. Bump date. 2010-09-28 16:25:27 +04:00			`.Nx 5.1 .`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`.Sh AUTHORS`
			`The`
			`.Nm`
			`driver was written by`
Use Mt for email addresses. 2013-07-21 01:39:55 +04:00			`.An Jared McNeill Aq Mt jmcneill@NetBSD.org`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`under contract by`
Quote company name because Lk macro takes only argument after URL. Cosmetic fix. 2012-08-14 00:31:15 +04:00			`.Lk http://www.precedence.co.uk/ "Precedence Technologies Ltd."`
Whitespace cleanup, sort sections, fix list. 2009-09-06 21:59:09 +04:00			`The UAA-compliant widget parser is derived from the`
			`.Fx`
			`snd_hda(4) driver.`
hdaudio(4) is a standards-compliant driver for Intel High Definition Audio. It will replace azalia(4) after testing. To use, comment out azalia in your kernel configuration and uncomment the hdaudio and hdafg lines so it reads: # Intel High Definition Audio hdaudio* at pci? dev ? function ? hdafg* at hdaudiobus? You should also: cd /dev sh MAKEDEV audio 2009-09-06 21:25:55 +04:00			`.Sh BUGS`
			`The following items are not yet implemented:`
Whitespace cleanup, sort sections, fix list. 2009-09-06 21:59:09 +04:00			`.Bl -bullet`
			`.It`
			`Improve power management support when driver is idle`
			`.It`
			`Add support for non-PCM output formats`
			`.It`
			`Handle unsolicited RIRB messages`
			`.It`
			`Modem function groups`
			`.El`