Merge remote-tracking branch 'sound/topic/restize-docs' into sound

Bring in the sphinxification of the sound documentation.

Merge remote-tracking branch 'sound/topic/restize-docs' into sound
Bring in the sphinxification of the sound documentation.
726d661f · Jonathan Corbet · 917fef6f · c6ab9e57 · 726d661f · 917fef6f
56 changed file
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -12,8 +12,7 @@ DOCBOOKS := z8530book.xml  \
 	    kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
 	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
-	    debugobjects.xml sh.xml regulator.xml \
+	    80211.xml debugobjects.xml sh.xml regulator.xml \
-	    alsa-driver-api.xml writing-an-alsa-driver.xml \
 	    tracepoint.xml w1.xml \
 	    writing_musb_glue_layer.xml crypto-API.xml iio.xml

--- a/Documentation/DocBook/alsa-driver-api.tmpl
+++ b/Documentation/DocBook/alsa-driver-api.tmpl
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-<!-- ****************************************************** -->
-<!-- Header  -->
-<!-- ****************************************************** -->
-<book id="ALSA-Driver-API">
-  <bookinfo>
-    <title>The ALSA Driver API</title>
-    <legalnotice>
-    <para>
-    This document is free; you can redistribute it and/or modify it
-    under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version. 
-    </para>
-    <para>
-    This document is distributed in the hope that it will be useful,
-    but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the
-    implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A
-    PARTICULAR PURPOSE</emphasis>. See the GNU General Public License
-    for more details.
-    </para>
-    <para>
-    You should have received a copy of the GNU General Public
-    License along with this program; if not, write to the Free
-    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-    MA 02111-1307 USA
-    </para>
-    </legalnotice>
-  </bookinfo>
-<toc></toc>
-  <chapter><title>Management of Cards and Devices</title>
-     <sect1><title>Card Management</title>
-!Esound/core/init.c
-     </sect1>
-     <sect1><title>Device Components</title>
-!Esound/core/device.c
-     </sect1>
-     <sect1><title>Module requests and Device File Entries</title>
-!Esound/core/sound.c
-     </sect1>
-     <sect1><title>Memory Management Helpers</title>
-!Esound/core/memory.c
-!Esound/core/memalloc.c
-     </sect1>
-  </chapter>
-  <chapter><title>PCM API</title>
-     <sect1><title>PCM Core</title>
-!Esound/core/pcm.c
-!Esound/core/pcm_lib.c
-!Esound/core/pcm_native.c
-!Iinclude/sound/pcm.h
-     </sect1>
-     <sect1><title>PCM Format Helpers</title>
-!Esound/core/pcm_misc.c
-     </sect1>
-     <sect1><title>PCM Memory Management</title>
-!Esound/core/pcm_memory.c
-     </sect1>
-     <sect1><title>PCM DMA Engine API</title>
-!Esound/core/pcm_dmaengine.c
-!Iinclude/sound/dmaengine_pcm.h
-     </sect1>
-  </chapter>
-  <chapter><title>Control/Mixer API</title>
-     <sect1><title>General Control Interface</title>
-!Esound/core/control.c
-     </sect1>
-     <sect1><title>AC97 Codec API</title>
-!Esound/pci/ac97/ac97_codec.c
-!Esound/pci/ac97/ac97_pcm.c
-     </sect1>
-     <sect1><title>Virtual Master Control API</title>
-!Esound/core/vmaster.c
-!Iinclude/sound/control.h
-     </sect1>
-  </chapter>
-  <chapter><title>MIDI API</title>
-     <sect1><title>Raw MIDI API</title>
-!Esound/core/rawmidi.c
-     </sect1>
-     <sect1><title>MPU401-UART API</title>
-!Esound/drivers/mpu401/mpu401_uart.c
-     </sect1>
-  </chapter>
-  <chapter><title>Proc Info API</title>
-     <sect1><title>Proc Info Interface</title>
-!Esound/core/info.c
-     </sect1>
-  </chapter>
-  <chapter><title>Compress Offload</title>
-     <sect1><title>Compress Offload API</title>
-!Esound/core/compress_offload.c
-!Iinclude/uapi/sound/compress_offload.h
-!Iinclude/uapi/sound/compress_params.h
-!Iinclude/sound/compress_driver.h
-     </sect1>
-  </chapter>
-  <chapter><title>ASoC</title>
-     <sect1><title>ASoC Core API</title>
-!Iinclude/sound/soc.h
-!Esound/soc/soc-core.c
-<!-- !Esound/soc/soc-cache.c no docbook comments here -->
-!Esound/soc/soc-devres.c
-!Esound/soc/soc-io.c
-!Esound/soc/soc-pcm.c
-!Esound/soc/soc-ops.c
-!Esound/soc/soc-compress.c
-     </sect1>
-     <sect1><title>ASoC DAPM API</title>
-!Esound/soc/soc-dapm.c
-     </sect1>
-     <sect1><title>ASoC DMA Engine API</title>
-!Esound/soc/soc-generic-dmaengine-pcm.c
-     </sect1>
-  </chapter>
-  <chapter><title>Miscellaneous Functions</title>
-     <sect1><title>Hardware-Dependent Devices API</title>
-!Esound/core/hwdep.c
-     </sect1>
-     <sect1><title>Jack Abstraction Layer API</title>
-!Iinclude/sound/jack.h
-!Esound/core/jack.c
-!Esound/soc/soc-jack.c
-     </sect1>
-     <sect1><title>ISA DMA Helpers</title>
-!Esound/core/isadma.c
-     </sect1>
-     <sect1><title>Other Helper Macros</title>
-!Iinclude/sound/core.h
-     </sect1>
-  </chapter>
-</book>
--- a/Documentation/DocBook/writing-an-alsa-driver.tmpl
+++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -58,6 +58,7 @@ needed).
   gpu/index
   80211/index
   security/index
+   sound/index
 Korean translations
 -------------------

--- a/Documentation/sound/alsa-configuration.rst
+++ b/Documentation/sound/alsa-configuration.rst
--- a/Documentation/sound/alsa/ALSA-Configuration.txt
+++ b/Documentation/sound/alsa/ALSA-Configuration.txt
--- a/Documentation/sound/alsa/ControlNames.txt
+++ b/Documentation/sound/alsa/ControlNames.txt
-This document describes standard names of mixer controls.
-Syntax: [LOCATION] SOURCE [CHANNEL] [DIRECTION] FUNCTION
-DIRECTION:
-  <nothing>	(both directions)
-  Playback
-  Capture
-  Bypass Playback
-  Bypass Capture
-FUNCTION:
-  Switch	(on/off switch)
-  Volume
-  Route		(route control, hardware specific)
-CHANNEL:
-  <nothing>     (channel independent, or applies to all channels)
-  Front
-  Surround      (rear left/right in 4.0/5.1 surround)
-  CLFE
-  Center
-  LFE
-  Side          (side left/right for 7.1 surround)
-LOCATION:       (physical location of source)
-  Front
-  Rear
-  Dock          (docking station)
-  Internal
-SOURCE:
-  Master
-  Master Mono
-  Hardware Master
-  Speaker	(internal speaker)
-  Bass Speaker	(internal LFE speaker)
-  Headphone
-  Line Out
-  Beep		(beep generator)
-  Phone
-  Phone Input
-  Phone Output
-  Synth
-  FM
-  Mic
-  Headset Mic	(mic part of combined headset jack - 4-pin headphone + mic)
-  Headphone Mic	(mic part of either/or - 3-pin headphone or mic)
-  Line		(input only, use "Line Out" for output)
-  CD
-  Video
-  Zoom Video
-  Aux
-  PCM
-  PCM Pan
-  Loopback
-  Analog Loopback	(D/A -> A/D loopback)
-  Digital Loopback	(playback -> capture loopback - without analog path)
-  Mono
-  Mono Output
-  Multi
-  ADC
-  Wave
-  Music
-  I2S
-  IEC958
-  HDMI
-  SPDIF		(output only)
-  SPDIF In
-  Digital In
-  HDMI/DP	(either HDMI or DisplayPort)
-Exceptions (deprecated):
-  [Analogue|Digital] Capture Source
-  [Analogue|Digital] Capture Switch	(aka input gain switch)
-  [Analogue|Digital] Capture Volume	(aka input gain volume)
-  [Analogue|Digital] Playback Switch	(aka output gain switch)
-  [Analogue|Digital] Playback Volume	(aka output gain volume)
-  Tone Control - Switch
-  Tone Control - Bass
-  Tone Control - Treble
-  3D Control - Switch
-  3D Control - Center
-  3D Control - Depth
-  3D Control - Wide
-  3D Control - Space
-  3D Control - Level
-  Mic Boost [(?dB)]
-PCM interface:
-  Sample Clock Source	{ "Word", "Internal", "AutoSync" }
-  Clock Sync Status	{ "Lock", "Sync", "No Lock" }
-  External Rate		/* external capture rate */
-  Capture Rate		/* capture rate taken from external source */
-IEC958 (S/PDIF) interface:
-  IEC958 [...] [Playback|Capture] Switch	/* turn on/off the IEC958 interface */
-  IEC958 [...] [Playback|Capture] Volume	/* digital volume control */
-  IEC958 [...] [Playback|Capture] Default	/* default or global value - read/write */
-  IEC958 [...] [Playback|Capture] Mask		/* consumer and professional mask */
-  IEC958 [...] [Playback|Capture] Con Mask	/* consumer mask */
-  IEC958 [...] [Playback|Capture] Pro Mask	/* professional mask */
-  IEC958 [...] [Playback|Capture] PCM Stream	/* the settings assigned to a PCM stream */
-  IEC958 Q-subcode [Playback|Capture] Default	/* Q-subcode bits */
-  IEC958 Preamble [Playback|Capture] Default	/* burst preamble words (4*16bits) */
--- a/Documentation/sound/alsa/HD-Audio-Models.txt
+++ b/Documentation/sound/alsa/HD-Audio-Models.txt
-  Model name	Description
-  ----------    -----------
-ALC880
-======
-  3stack	3-jack in back and a headphone out
-  3stack-digout	3-jack in back, a HP out and a SPDIF out
-  5stack	5-jack in back, 2-jack in front
-  5stack-digout	5-jack in back, 2-jack in front, a SPDIF out
-  6stack	6-jack in back, 2-jack in front
-  6stack-digout	6-jack with a SPDIF out
-ALC260
-======
-  gpio1		Enable GPIO1
-  coef		Enable EAPD via COEF table
-  fujitsu	Quirk for FSC S7020
-  fujitsu-jwse	Quirk for FSC S7020 with jack modes and HP mic support
-ALC262
-======
-  inv-dmic	Inverted internal mic workaround
-ALC267/268
-==========
-  inv-dmic	Inverted internal mic workaround
-  hp-eapd	Disable HP EAPD on NID 0x15
-ALC22x/23x/25x/269/27x/28x/29x (and vendor-specific ALC3xxx models)
-======
-  laptop-amic		Laptops with analog-mic input
-  laptop-dmic		Laptops with digital-mic input
-  alc269-dmic		Enable ALC269(VA) digital mic workaround
-  alc271-dmic		Enable ALC271X digital mic workaround
-  inv-dmic		Inverted internal mic workaround
-  headset-mic		Indicates a combined headset (headphone+mic) jack
-  headset-mode		More comprehensive headset support for ALC269 & co
-  headset-mode-no-hp-mic Headset mode support without headphone mic
-  lenovo-dock   	Enables docking station I/O for some Lenovos
-  hp-gpio-led		GPIO LED support on HP laptops
-  dell-headset-multi	Headset jack, which can also be used as mic-in
-  dell-headset-dock	Headset jack (without mic-in), and also dock I/O
-  alc283-dac-wcaps	Fixups for Chromebook with ALC283
-  alc283-sense-combo	Combo jack sensing on ALC283
-  tpt440-dock		Pin configs for Lenovo Thinkpad Dock support
-ALC66x/67x/892
-==============
-  mario			Chromebook mario model fixup
-  asus-mode1		ASUS
-  asus-mode2		ASUS
-  asus-mode3		ASUS
-  asus-mode4		ASUS
-  asus-mode5		ASUS
-  asus-mode6		ASUS
-  asus-mode7		ASUS
-  asus-mode8		ASUS
-  inv-dmic		Inverted internal mic workaround
-  dell-headset-multi	Headset jack, which can also be used as mic-in
-ALC680
-======
-  N/A
-ALC88x/898/1150
-======================
-  acer-aspire-4930g	Acer Aspire 4930G/5930G/6530G/6930G/7730G
-  acer-aspire-8930g	Acer Aspire 8330G/6935G
-  acer-aspire		Acer Aspire others
-  inv-dmic		Inverted internal mic workaround
-  no-primary-hp		VAIO Z/VGC-LN51JGB workaround (for fixed speaker DAC)
-ALC861/660
-==========
-  N/A
-ALC861VD/660VD
-==============
-  N/A
-CMI9880
-=======
-  minimal	3-jack in back
-  min_fp	3-jack in back, 2-jack in front
-  full		6-jack in back, 2-jack in front
-  full_dig	6-jack in back, 2-jack in front, SPDIF I/O
-  allout	5-jack in back, 2-jack in front, SPDIF out
-  auto		auto-config reading BIOS (default)
-AD1882 / AD1882A
-================
-  3stack	3-stack mode
-  3stack-automute 3-stack with automute front HP (default)
-  6stack	6-stack mode
-AD1884A / AD1883 / AD1984A / AD1984B
-====================================
-  desktop	3-stack desktop (default)
-  laptop	laptop with HP jack sensing
-  mobile	mobile devices with HP jack sensing
-  thinkpad	Lenovo Thinkpad X300
-  touchsmart	HP Touchsmart
-AD1884
-======
-  N/A
-AD1981
-======
-  basic		3-jack (default)
-  hp		HP nx6320
-  thinkpad	Lenovo Thinkpad T60/X60/Z60
-  toshiba	Toshiba U205
-AD1983
-======
-  N/A
-AD1984
-======
-  basic		default configuration
-  thinkpad	Lenovo Thinkpad T61/X61
-  dell_desktop	Dell T3400
-AD1986A
-=======
-  3stack	3-stack, shared surrounds
-  laptop	2-channel only (FSC V2060, Samsung M50)
-  laptop-imic	2-channel with built-in mic
-  eapd		Turn on EAPD constantly
-AD1988/AD1988B/AD1989A/AD1989B
-==============================
-  6stack	6-jack
-  6stack-dig	ditto with SPDIF
-  3stack	3-jack
-  3stack-dig	ditto with SPDIF
-  laptop	3-jack with hp-jack automute
-  laptop-dig	ditto with SPDIF
-  auto		auto-config reading BIOS (default)
-Conexant 5045
-=============
-  laptop-hpsense    Laptop with HP sense (old model laptop)
-  laptop-micsense   Laptop with Mic sense (old model fujitsu)
-  laptop-hpmicsense Laptop with HP and Mic senses
-  benq		Benq R55E
-  laptop-hp530	HP 530 laptop
-  test		for testing/debugging purpose, almost all controls
-		can be adjusted.  Appearing only when compiled with
-		$CONFIG_SND_DEBUG=y
-Conexant 5047
-=============
-  laptop	Basic Laptop config 
-  laptop-hp	Laptop config for some HP models (subdevice 30A5)
-  laptop-eapd	Laptop config with EAPD support
-  test		for testing/debugging purpose, almost all controls
-		can be adjusted.  Appearing only when compiled with
-		$CONFIG_SND_DEBUG=y
-Conexant 5051
-=============
-  laptop	Basic Laptop config (default)
-  hp		HP Spartan laptop
-  hp-dv6736	HP dv6736
-  hp-f700	HP Compaq Presario F700
-  ideapad	Lenovo IdeaPad laptop
-  toshiba	Toshiba Satellite M300
-Conexant 5066
-=============
-  laptop	Basic Laptop config (default)
-  hp-laptop	HP laptops, e g G60
-  asus		Asus K52JU, Lenovo G560
-  dell-laptop	Dell laptops
-  dell-vostro	Dell Vostro
-  olpc-xo-1_5	OLPC XO 1.5
-  ideapad       Lenovo IdeaPad U150
-  thinkpad	Lenovo Thinkpad
-STAC9200
-========
-  ref		Reference board
-  oqo		OQO Model 2
-  dell-d21	Dell (unknown)
-  dell-d22	Dell (unknown)
-  dell-d23	Dell (unknown)
-  dell-m21	Dell Inspiron 630m, Dell Inspiron 640m
-  dell-m22	Dell Latitude D620, Dell Latitude D820
-  dell-m23	Dell XPS M1710, Dell Precision M90
-  dell-m24	Dell Latitude 120L
-  dell-m25	Dell Inspiron E1505n
-  dell-m26	Dell Inspiron 1501
-  dell-m27	Dell Inspiron E1705/9400
-  gateway-m4	Gateway laptops with EAPD control
-  gateway-m4-2	Gateway laptops with EAPD control
-  panasonic	Panasonic CF-74
-  auto		BIOS setup (default)
-STAC9205/9254
-=============
-  ref		Reference board
-  dell-m42	Dell (unknown)
-  dell-m43	Dell Precision
-  dell-m44	Dell Inspiron
-  eapd		Keep EAPD on (e.g. Gateway T1616)
-  auto		BIOS setup (default)
-STAC9220/9221
-=============
-  ref		Reference board
-  3stack	D945 3stack
-  5stack	D945 5stack + SPDIF
-  intel-mac-v1	Intel Mac Type 1
-  intel-mac-v2	Intel Mac Type 2
-  intel-mac-v3	Intel Mac Type 3
-  intel-mac-v4	Intel Mac Type 4
-  intel-mac-v5	Intel Mac Type 5
-  intel-mac-auto Intel Mac (detect type according to subsystem id)
-  macmini	Intel Mac Mini (equivalent with type 3)
-  macbook	Intel Mac Book (eq. type 5)
-  macbook-pro-v1 Intel Mac Book Pro 1st generation (eq. type 3)
-  macbook-pro	Intel Mac Book Pro 2nd generation (eq. type 3)
-  imac-intel	Intel iMac (eq. type 2)
-  imac-intel-20	Intel iMac (newer version) (eq. type 3)
-  ecs202	ECS/PC chips
-  dell-d81	Dell (unknown)
-  dell-d82	Dell (unknown)
-  dell-m81	Dell (unknown)
-  dell-m82	Dell XPS M1210
-  auto		BIOS setup (default)
-STAC9202/9250/9251
-==================
-  ref		Reference board, base config
-  m1		Some Gateway MX series laptops (NX560XL)
-  m1-2		Some Gateway MX series laptops (MX6453)
-  m2		Some Gateway MX series laptops (M255)
-  m2-2		Some Gateway MX series laptops
-  m3		Some Gateway MX series laptops
-  m5		Some Gateway MX series laptops (MP6954)
-  m6		Some Gateway NX series laptops
-  auto		BIOS setup (default)
-STAC9227/9228/9229/927x
-=======================
-  ref		Reference board
-  ref-no-jd	Reference board without HP/Mic jack detection
-  3stack	D965 3stack
-  5stack	D965 5stack + SPDIF
-  5stack-no-fp	D965 5stack without front panel
-  dell-3stack	Dell Dimension E520
-  dell-bios	Fixes with Dell BIOS setup
-  dell-bios-amic Fixes with Dell BIOS setup including analog mic
-  volknob	Fixes with volume-knob widget 0x24
-  auto		BIOS setup (default)
-STAC92HD71B*
-============
-  ref		Reference board
-  dell-m4-1	Dell desktops
-  dell-m4-2	Dell desktops
-  dell-m4-3	Dell desktops
-  hp-m4		HP mini 1000
-  hp-dv5	HP dv series
-  hp-hdx	HP HDX series
-  hp-dv4-1222nr	HP dv4-1222nr (with LED support)
-  auto		BIOS setup (default)
-STAC92HD73*
-===========
-  ref		Reference board
-  no-jd		BIOS setup but without jack-detection
-  intel		Intel DG45* mobos
-  dell-m6-amic	Dell desktops/laptops with analog mics
-  dell-m6-dmic	Dell desktops/laptops with digital mics
-  dell-m6	Dell desktops/laptops with both type of mics
-  dell-eq	Dell desktops/laptops
-  alienware	Alienware M17x
-  auto		BIOS setup (default)
-STAC92HD83*
-===========
-  ref		Reference board
-  mic-ref	Reference board with power management for ports
-  dell-s14	Dell laptop
-  dell-vostro-3500	Dell Vostro 3500 laptop
-  hp-dv7-4000	HP dv-7 4000
-  hp_cNB11_intquad HP CNB models with 4 speakers
-  hp-zephyr	HP Zephyr
-  hp-led	HP with broken BIOS for mute LED
-  hp-inv-led	HP with broken BIOS for inverted mute LED
-  hp-mic-led	HP with mic-mute LED
-  headset-jack	Dell Latitude with a 4-pin headset jack
-  hp-envy-bass	Pin fixup for HP Envy bass speaker (NID 0x0f)
-  hp-envy-ts-bass Pin fixup for HP Envy TS bass speaker (NID 0x10)
-  hp-bnb13-eq	Hardware equalizer setup for HP laptops
-  auto		BIOS setup (default)
-STAC92HD95
-==========
-  hp-led	LED support for HP laptops
-  hp-bass	Bass HPF setup for HP Spectre 13
-STAC9872
-========
-  vaio		VAIO laptop without SPDIF
-  auto		BIOS setup (default)
-Cirrus Logic CS4206/4207
-========================
-  mbp55		MacBook Pro 5,5
-  imac27	IMac 27 Inch
-  auto		BIOS setup (default)
-Cirrus Logic CS4208
-===================
-  mba6		MacBook Air 6,1 and 6,2
-  gpio0		Enable GPIO 0 amp
-  auto		BIOS setup (default)
-VIA VT17xx/VT18xx/VT20xx
-========================
-  auto		BIOS setup (default)
--- a/Documentation/sound/alsa/VIA82xx-mixer.txt
+++ b/Documentation/sound/alsa/VIA82xx-mixer.txt
-				VIA82xx mixer
-				=============
-On many VIA82xx boards, the 'Input Source Select' mixer control does not work.
-Setting it to 'Input2' on such boards will cause recording to hang, or fail
-with EIO (input/output error) via OSS emulation.  This control should be left
-at 'Input1' for such cards.
--- a/Documentation/sound/alsa/alsa-parameters.txt
+++ b/Documentation/sound/alsa/alsa-parameters.txt
-                          ALSA Kernel Parameters
-                          ~~~~~~~~~~~~~~~~~~~~~~
-See Documentation/admin-guide/kernel-parameters.rst for general information on
-specifying module parameters.
-This document may not be entirely up to date and comprehensive. The command
-"modinfo -p ${modulename}" shows a current list of all parameters of a loadable
-module. Loadable modules, after being loaded into the running kernel, also
-reveal their parameters in /sys/module/${modulename}/parameters/. Some of these
-parameters may be changed at runtime by the command
-"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}".
-	snd-ad1816a=	[HW,ALSA]
-	snd-ad1848=	[HW,ALSA]
-	snd-ali5451=	[HW,ALSA]
-	snd-als100=	[HW,ALSA]
-	snd-als4000=	[HW,ALSA]
-	snd-azt2320=	[HW,ALSA]
-	snd-cmi8330=	[HW,ALSA]
-	snd-cmipci=	[HW,ALSA]
-	snd-cs4231=	[HW,ALSA]
-	snd-cs4232=	[HW,ALSA]
-	snd-cs4236=	[HW,ALSA]
-	snd-cs4281=	[HW,ALSA]
-	snd-cs46xx=	[HW,ALSA]
-	snd-dt019x=	[HW,ALSA]
-	snd-dummy=	[HW,ALSA]
-	snd-emu10k1=	[HW,ALSA]
-	snd-ens1370=	[HW,ALSA]
-	snd-ens1371=	[HW,ALSA]
-	snd-es968=	[HW,ALSA]
-	snd-es1688=	[HW,ALSA]
-	snd-es18xx=	[HW,ALSA]
-	snd-es1938=	[HW,ALSA]
-	snd-es1968=	[HW,ALSA]
-	snd-fm801=	[HW,ALSA]
-	snd-gusclassic=	[HW,ALSA]
-	snd-gusextreme=	[HW,ALSA]
-	snd-gusmax=	[HW,ALSA]
-	snd-hdsp=	[HW,ALSA]
-	snd-ice1712=	[HW,ALSA]
-	snd-intel8x0=	[HW,ALSA]
-	snd-interwave=	[HW,ALSA]
-	snd-interwave-stb=
-			[HW,ALSA]
-	snd-korg1212=	[HW,ALSA]
-	snd-maestro3=	[HW,ALSA]
-	snd-mpu401=	[HW,ALSA]
-	snd-mtpav=	[HW,ALSA]
-	snd-nm256=	[HW,ALSA]
-	snd-opl3sa2=	[HW,ALSA]
-	snd-opti92x-ad1848=
-			[HW,ALSA]
-	snd-opti92x-cs4231=
-			[HW,ALSA]
-	snd-opti93x=	[HW,ALSA]
-	snd-pmac=	[HW,ALSA]
-	snd-rme32=	[HW,ALSA]
-	snd-rme96=	[HW,ALSA]
-	snd-rme9652=	[HW,ALSA]
-	snd-sb8=	[HW,ALSA]
-	snd-sb16=	[HW,ALSA]
-	snd-sbawe=	[HW,ALSA]
-	snd-serial=	[HW,ALSA]
-	snd-sgalaxy=	[HW,ALSA]
-	snd-sonicvibes=	[HW,ALSA]
-	snd-sun-amd7930=
-			[HW,ALSA]
-	snd-sun-cs4231=	[HW,ALSA]
-	snd-trident=	[HW,ALSA]
-	snd-usb-audio=	[HW,ALSA,USB]
-	snd-via82xx=	[HW,ALSA]
-	snd-virmidi=	[HW,ALSA]
-	snd-wavefront=	[HW,ALSA]
-	snd-ymfpci=	[HW,ALSA]
--- a/Documentation/sound/alsa/seq_oss.html
+++ b/Documentation/sound/alsa/seq_oss.html
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<HTML>
-<HEAD>
-   <TITLE>OSS Sequencer Emulation on ALSA</TITLE>
-</HEAD>
-<BODY>
-<CENTER>
-<H1>
-<HR WIDTH="100%"></H1></CENTER>
-<CENTER>
-<H1>
-OSS Sequencer Emulation on ALSA</H1></CENTER>
-<HR WIDTH="100%">
-<P>Copyright (c) 1998,1999 by Takashi Iwai
-<TT><A HREF="mailto:iwai@ww.uni-erlangen.de">&lt;iwai@ww.uni-erlangen.de></A></TT>
-<P>ver.0.1.8; Nov. 16, 1999
-<H2>
-<HR WIDTH="100%"></H2>
-<H2>
-1. Description</H2>
-This directory contains the OSS sequencer emulation driver on ALSA. Note
-that this program is still in the development state.
-<P>What this does - it provides the emulation of the OSS sequencer, access
-via
-<TT>/dev/sequencer</TT> and <TT>/dev/music</TT> devices.
-The most of applications using OSS can run if the appropriate ALSA
-sequencer is prepared.
-<P>The following features are emulated by this driver:
-<UL>
-<LI>
-Normal sequencer and MIDI events:</LI>
-<BR>They are converted to the ALSA sequencer events, and sent to the corresponding
-port.
-<LI>
-Timer events:</LI>
-<BR>The timer is not selectable by ioctl. The control rate is fixed to
-100 regardless of HZ. That is, even on Alpha system, a tick is always
-1/100 second. The base rate and tempo can be changed in <TT>/dev/music</TT>.
-<LI>
-Patch loading:</LI>
-<BR>It purely depends on the synth drivers whether it's supported since
-the patch loading is realized by callback to the synth driver.
-<LI>
-I/O controls:</LI>
-<BR>Most of controls are accepted. Some controls
-are dependent on the synth driver, as well as even on original OSS.</UL>
-Furthermore, you can find the following advanced features:
-<UL>
-<LI>
-Better queue mechanism:</LI>
-<BR>The events are queued before processing them.
-<LI>
-Multiple applications:</LI>
-<BR>You can run two or more applications simultaneously (even for OSS sequencer)!
-However, each MIDI device is exclusive - that is, if a MIDI device is opened
-once by some application, other applications can't use it. No such a restriction
-in synth devices.
-<LI>
-Real-time event processing:</LI>
-<BR>The events can be processed in real time without using out of bound
-ioctl. To switch to real-time mode, send ABSTIME 0 event. The followed
-events will be processed in real-time without queued. To switch off the
-real-time mode, send RELTIME 0 event.
-<LI>
-<TT>/proc</TT> interface:</LI>
-<BR>The status of applications and devices can be shown via <TT>/proc/asound/seq/oss</TT>
-at any time. In the later version, configuration will be changed via <TT>/proc</TT>
-interface, too.</UL>
-<H2>
-2. Installation</H2>
-Run configure script with both sequencer support (<TT>--with-sequencer=yes</TT>)
-and OSS emulation (<TT>--with-oss=yes</TT>) options. A module <TT>snd-seq-oss.o</TT>
-will be created. If the synth module of your sound card supports for OSS
-emulation (so far, only Emu8000 driver), this module will be loaded automatically.
-Otherwise, you need to load this module manually.
-<P>At beginning, this module probes all the MIDI ports which have been
-already connected to the sequencer. Once after that, the creation and deletion
-of ports are watched by announcement mechanism of ALSA sequencer.
-<P>The available synth and MIDI devices can be found in proc interface.
-Run "<TT>cat /proc/asound/seq/oss</TT>", and check the devices. For example,
-if you use an AWE64 card, you'll see like the following:
-<PRE>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; OSS sequencer emulation version 0.1.8
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ALSA client number 63
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ALSA receiver port 0
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Number of applications: 0
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Number of synth devices: 1
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; synth 0: [EMU8000]
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; type 0x1 : subtype 0x20 : voices 32
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; capabilties : ioctl enabled / load_patch enabled
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Number of MIDI devices: 3
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; midi 0: [Emu8000 Port-0] ALSA port 65:0
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; capability write / opened none
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; midi 1: [Emu8000 Port-1] ALSA port 65:1
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; capability write / opened none
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; midi 2: [0: MPU-401 (UART)] ALSA port 64:0
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; capability read/write / opened none</PRE>
-Note that the device number may be different from the information of
-<TT>/proc/asound/oss-devices</TT>
-or ones of the original OSS driver. Use the device number listed in <TT>/proc/asound/seq/oss</TT>
-to play via OSS sequencer emulation.
-<H2>
-3. Using Synthesizer Devices</H2>
-Run your favorite program. I've tested playmidi-2.4, awemidi-0.4.3, gmod-3.1
-and xmp-1.1.5. You can load samples via <TT>/dev/sequencer</TT> like sfxload,
-too.
-<P>If the lowlevel driver supports multiple access to synth devices (like
-Emu8000 driver), two or more applications are allowed to run at the same
-time.
-<H2>
-4. Using MIDI Devices</H2>
-So far, only MIDI output was tested. MIDI input was not checked at all,
-but hopefully it will work. Use the device number listed in <TT>/proc/asound/seq/oss</TT>.
-Be aware that these numbers are mostly different from the list in
-<TT>/proc/asound/oss-devices</TT>.
-<H2>
-5. Module Options</H2>
-The following module options are available:
-<UL>
-<LI>
-<TT>maxqlen</TT></LI>
-<BR>specifies the maximum read/write queue length. This queue is private
-for OSS sequencer, so that it is independent from the queue length of ALSA
-sequencer. Default value is 1024.
-<LI>
-<TT>seq_oss_debug</TT></LI>
-<BR>specifies the debug level and accepts zero (= no debug message) or
-positive integer. Default value is 0.</UL>
-<H2>
-6. Queue Mechanism</H2>
-OSS sequencer emulation uses an ALSA priority queue. The
-events from <TT>/dev/sequencer</TT> are processed and put onto the queue
-specified by module option.
-<P>All the events from <TT>/dev/sequencer</TT> are parsed at beginning.
-The timing events are also parsed at this moment, so that the events may
-be processed in real-time. Sending an event ABSTIME 0 switches the operation
-mode to real-time mode, and sending an event RELTIME 0 switches it off.
-In the real-time mode, all events are dispatched immediately.
-<P>The queued events are dispatched to the corresponding ALSA sequencer
-ports after scheduled time by ALSA sequencer dispatcher.
-<P>If the write-queue is full, the application sleeps until a certain amount
-(as default one half) becomes empty in blocking mode. The synchronization
-to write timing was implemented, too.
-<P>The input from MIDI devices or echo-back events are stored on read FIFO
-queue. If application reads <TT>/dev/sequencer</TT> in blocking mode, the
-process will be awaked.
-<H2>
-7. Interface to Synthesizer Device</H2>
-<H3>
-7.1. Registration</H3>
-To register an OSS synthesizer device, use <TT>snd_seq_oss_synth_register</TT>
-function.
-<PRE>int snd_seq_oss_synth_register(char *name, int type, int subtype, int nvoices,
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; snd_seq_oss_callback_t *oper, void *private_data)</PRE>
-The arguments <TT>name</TT>, <TT>type</TT>, <TT>subtype</TT> and
-<TT>nvoices</TT>
-are used for making the appropriate synth_info structure for ioctl. The
-return value is an index number of this device. This index must be remembered
-for unregister. If registration is failed, -errno will be returned.
-<P>To release this device, call <TT>snd_seq_oss_synth_unregister function</TT>:
-<PRE>int snd_seq_oss_synth_unregister(int index),</PRE>
-where the <TT>index</TT> is the index number returned by register function.
-<H3>
-7.2. Callbacks</H3>
-OSS synthesizer devices have capability for sample downloading and ioctls
-like sample reset. In OSS emulation, these special features are realized
-by using callbacks. The registration argument oper is used to specify these
-callbacks. The following callback functions must be defined:
-<PRE>snd_seq_oss_callback_t:
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int (*open)(snd_seq_oss_arg_t *p, void *closure);
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int (*close)(snd_seq_oss_arg_t *p);
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int (*ioctl)(snd_seq_oss_arg_t *p, unsigned int cmd, unsigned long arg);
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int (*load_patch)(snd_seq_oss_arg_t *p, int format, const char *buf, int offs, int count);
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int (*reset)(snd_seq_oss_arg_t *p);
-Except for <TT>open</TT> and <TT>close</TT> callbacks, they are allowed
-to be NULL.
-<P>Each callback function takes the argument type snd_seq_oss_arg_t as the
-first argument.
-<PRE>struct snd_seq_oss_arg_t {
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int app_index;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int file_mode;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int seq_mode;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; snd_seq_addr_t addr;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *private_data;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int event_passing;
-};</PRE>
-The first three fields, <TT>app_index</TT>, <TT>file_mode</TT> and
-<TT>seq_mode</TT>
-are initialized by OSS sequencer. The <TT>app_index</TT> is the application
-index which is unique to each application opening OSS sequencer. The
-<TT>file_mode</TT>
-is bit-flags indicating the file operation mode. See
-<TT>seq_oss.h</TT>
-for its meaning. The <TT>seq_mode</TT> is sequencer operation mode. In
-the current version, only <TT>SND_OSSSEQ_MODE_SYNTH</TT> is used.
-<P>The next two fields, <TT>addr</TT> and <TT>private_data</TT>, must be
-filled by the synth driver at open callback. The <TT>addr</TT> contains
-the address of ALSA sequencer port which is assigned to this device. If
-the driver allocates memory for <TT>private_data</TT>, it must be released
-in close callback by itself.
-<P>The last field, <TT>event_passing</TT>, indicates how to translate note-on
-/ off events. In <TT>PROCESS_EVENTS</TT> mode, the note 255 is regarded
-as velocity change, and key pressure event is passed to the port. In <TT>PASS_EVENTS</TT>
-mode, all note on/off events are passed to the port without modified. <TT>PROCESS_KEYPRESS</TT>
-mode checks the note above 128 and regards it as key pressure event (mainly
-for Emu8000 driver).
-<H4>
-7.2.1. Open Callback</H4>
-The <TT>open</TT> is called at each time this device is opened by an application
-using OSS sequencer. This must not be NULL. Typically, the open callback
-does the following procedure:
-<OL>
-<LI>
-Allocate private data record.</LI>
-<LI>
-Create an ALSA sequencer port.</LI>
-<LI>
-Set the new port address on arg->addr.</LI>
-<LI>
-Set the private data record pointer on arg->private_data.</LI>
-</OL>
-Note that the type bit-flags in port_info of this synth port must NOT contain
-<TT>TYPE_MIDI_GENERIC</TT>
-bit. Instead, <TT>TYPE_SPECIFIC</TT> should be used. Also, <TT>CAP_SUBSCRIPTION</TT>
-bit should NOT be included, too. This is necessary to tell it from other
-normal MIDI devices. If the open procedure succeeded, return zero. Otherwise,
-return -errno.
-<H4>
-7.2.2 Ioctl Callback</H4>
-The <TT>ioctl</TT> callback is called when the sequencer receives device-specific
-ioctls. The following two ioctls should be processed by this callback:
-<UL>
-<LI>
-<TT>IOCTL_SEQ_RESET_SAMPLES</TT></LI>
-<BR>reset all samples on memory -- return 0
-<LI>
-<TT>IOCTL_SYNTH_MEMAVL</TT></LI>
-<BR>return the available memory size
-<LI>
-<TT>FM_4OP_ENABLE</TT></LI>
-<BR>can be ignored usually</UL>
-The other ioctls are processed inside the sequencer without passing to
-the lowlevel driver.
-<H4>
-7.2.3 Load_Patch Callback</H4>
-The <TT>load_patch</TT> callback is used for sample-downloading. This callback
-must read the data on user-space and transfer to each device. Return 0
-if succeeded, and -errno if failed. The format argument is the patch key
-in patch_info record. The buf is user-space pointer where patch_info record
-is stored. The offs can be ignored. The count is total data size of this
-sample data.
-<H4>
-7.2.4 Close Callback</H4>
-The <TT>close</TT> callback is called when this device is closed by the
-application. If any private data was allocated in open callback, it must
-be released in the close callback. The deletion of ALSA port should be
-done here, too. This callback must not be NULL.
-<H4>
-7.2.5 Reset Callback</H4>
-The <TT>reset</TT> callback is called when sequencer device is reset or
-closed by applications. The callback should turn off the sounds on the
-relevant port immediately, and initialize the status of the port. If this
-callback is undefined, OSS seq sends a <TT>HEARTBEAT</TT> event to the
-port.
-<H3>
-7.3 Events</H3>
-Most of the events are processed by sequencer and translated to the adequate
-ALSA sequencer events, so that each synth device can receive by input_event
-callback of ALSA sequencer port. The following ALSA events should be implemented
-by the driver:
-<BR>&nbsp;
-<TABLE BORDER WIDTH="75%" NOSAVE >
-<TR NOSAVE>
-<TD NOSAVE><B>ALSA event</B></TD>
-<TD><B>Original OSS events</B></TD>
-</TR>
-<TR>
-<TD>NOTEON</TD>
-<TD>SEQ_NOTEON
-<BR>MIDI_NOTEON</TD>
-</TR>
-<TR>
-<TD>NOTE</TD>
-<TD>SEQ_NOTEOFF
-<BR>MIDI_NOTEOFF</TD>
-</TR>
-<TR NOSAVE>
-<TD NOSAVE>KEYPRESS</TD>
-<TD>MIDI_KEY_PRESSURE</TD>
-</TR>
-<TR NOSAVE>
-<TD>CHANPRESS</TD>
-<TD NOSAVE>SEQ_AFTERTOUCH
-<BR>MIDI_CHN_PRESSURE</TD>
-</TR>
-<TR NOSAVE>
-<TD NOSAVE>PGMCHANGE</TD>
-<TD NOSAVE>SEQ_PGMCHANGE
-<BR>MIDI_PGM_CHANGE</TD>
-</TR>
-<TR>
-<TD>PITCHBEND</TD>
-<TD>SEQ_CONTROLLER(CTRL_PITCH_BENDER)
-<BR>MIDI_PITCH_BEND</TD>
-</TR>
-<TR>
-<TD>CONTROLLER</TD>
-<TD>MIDI_CTL_CHANGE
-<BR>SEQ_BALANCE (with CTL_PAN)</TD>
-</TR>
-<TR>
-<TD>CONTROL14</TD>
-<TD>SEQ_CONTROLLER</TD>
-</TR>
-<TR>
-<TD>REGPARAM</TD>
-<TD>SEQ_CONTROLLER(CTRL_PITCH_BENDER_RANGE)</TD>
-</TR>
-<TR>
-<TD>SYSEX</TD>
-<TD>SEQ_SYSEX</TD>
-</TR>
-</TABLE>
-<P>The most of these behavior can be realized by MIDI emulation driver
-included in the Emu8000 lowlevel driver. In the future release, this module
-will be independent.
-<P>Some OSS events (<TT>SEQ_PRIVATE</TT> and <TT>SEQ_VOLUME</TT> events) are passed as event
-type SND_SEQ_OSS_PRIVATE.  The OSS sequencer passes these event 8 byte
-packets without any modification. The lowlevel driver should process these
-events appropriately.
-<H2>
-8. Interface to MIDI Device</H2>
-Since the OSS emulation probes the creation and deletion of ALSA MIDI sequencer
-ports automatically by receiving announcement from ALSA sequencer, the
-MIDI devices don't need to be registered explicitly like synth devices.
-However, the MIDI port_info registered to ALSA sequencer must include a group
-name <TT>SND_SEQ_GROUP_DEVICE</TT> and a capability-bit <TT>CAP_READ</TT> or
-<TT>CAP_WRITE</TT>. Also, subscription capabilities, <TT>CAP_SUBS_READ</TT> or <TT>CAP_SUBS_WRITE</TT>,
-must be defined, too. If these conditions are not satisfied, the port is not
-registered as OSS sequencer MIDI device.
-<P>The events via MIDI devices are parsed in OSS sequencer and converted
-to the corresponding ALSA sequencer events. The input from MIDI sequencer
-is also converted to MIDI byte events by OSS sequencer. This works just
-a reverse way of seq_midi module.
-<H2>
-9. Known Problems / TODO's</H2>
-<UL>
-<LI>
-Patch loading via ALSA instrument layer is not implemented yet.</LI>
-</UL>
-</BODY>
-</HTML>
--- a/Documentation/sound/alsa/Audigy-mixer.txt
+++ b/Documentation/sound/alsa/Audigy-mixer.txt
+=============================================
+Sound Blaster Audigy mixer / default DSP code
+=============================================
-		Sound Blaster Audigy mixer / default DSP code
+This is based on sb-live-mixer.rst.
-		===========================================
-This is based on SB-Live-mixer.txt.
 The EMU10K2 chips have a DSP part which can be programmed to support 
 various ways of sample processing, which is described here.
@@ -13,8 +13,8 @@ The ALSA driver programs this portion of chip by default code
 (can be altered later) which offers the following functionality:
-1) Digital mixer controls
+Digital mixer controls
-------------------------
+======================
 These controls are built using the DSP instructions. They offer extended
 functionality. Only the default build-in code in the ALSA driver is described
@@ -26,320 +26,343 @@ is mentioned in multiple controls, the signal is accumulated and can be wrapped
 Explanation of used abbreviations:
-DAC    - digital to analog converter
+DAC
-ADC    - analog to digital converter
+	digital to analog converter
-I2S    - one-way three wire serial bus for digital sound by Philips Semiconductors
+ADC
-         (this standard is used for connecting standalone DAC and ADC converters)
+	analog to digital converter
-LFE    - low frequency effects (subwoofer signal)
+I2S
-AC97   - a chip containing an analog mixer, DAC and ADC converters
+	one-way three wire serial bus for digital sound by Philips Semiconductors
-IEC958 - S/PDIF
+        (this standard is used for connecting standalone DAC and ADC converters)
-FX-bus - the EMU10K2 chip has an effect bus containing 64 accumulators.
+LFE
-         Each of the synthesizer voices can feed its output to these accumulators
+	low frequency effects (subwoofer signal)
-         and the DSP microcontroller can operate with the resulting sum.
+AC97
+	a chip containing an analog mixer, DAC and ADC converters
+IEC958
+	S/PDIF
+FX-bus
+	the EMU10K2 chip has an effect bus containing 64 accumulators.
+        Each of the synthesizer voices can feed its output to these accumulators
+        and the DSP microcontroller can operate with the resulting sum.
 name='PCM Front Playback Volume',index=0
+----------------------------------------
 This control is used to attenuate samples for left and right front PCM FX-bus
 accumulators. ALSA uses accumulators 8 and 9 for left and right front PCM 
 samples for 5.1 playback. The result samples are forwarded to the front DAC PCM 
 slots of the Philips DAC.
 name='PCM Surround Playback Volume',index=0
+-------------------------------------------
 This control is used to attenuate samples for left and right surround PCM FX-bus
 accumulators. ALSA uses accumulators 2 and 3 for left and right surround PCM 
 samples for 5.1 playback. The result samples are forwarded to the surround DAC PCM 
 slots of the Philips DAC.
 name='PCM Center Playback Volume',index=0
+-----------------------------------------
 This control is used to attenuate samples for center PCM FX-bus accumulator.
 ALSA uses accumulator 6 for center PCM sample for 5.1 playback. The result sample
 is forwarded to the center DAC PCM slot of the Philips DAC.
 name='PCM LFE Playback Volume',index=0
+--------------------------------------
 This control is used to attenuate sample for LFE PCM FX-bus accumulator. 
 ALSA uses accumulator 7 for LFE PCM sample for 5.1 playback. The result sample 
 is forwarded to the LFE DAC PCM slot of the Philips DAC.
 name='PCM Playback Volume',index=0
+----------------------------------
 This control is used to attenuate samples for left and right PCM FX-bus
 accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples for
 stereo playback. The result samples are forwarded to the front DAC PCM slots 
 of the Philips DAC.
 name='PCM Capture Volume',index=0
+---------------------------------
 This control is used to attenuate samples for left and right PCM FX-bus
 accumulator. ALSA uses accumulators 0 and 1 for left and right PCM.
 The result is forwarded to the ADC capture FIFO (thus to the standard capture
 PCM device).
 name='Music Playback Volume',index=0
+------------------------------------
 This control is used to attenuate samples for left and right MIDI FX-bus
 accumulators. ALSA uses accumulators 4 and 5 for left and right MIDI samples.
 The result samples are forwarded to the front DAC PCM slots of the AC97 codec.
 name='Music Capture Volume',index=0
+-----------------------------------
 These controls are used to attenuate samples for left and right MIDI FX-bus
 accumulator. ALSA uses accumulators 4 and 5 for left and right PCM.
 The result is forwarded to the ADC capture FIFO (thus to the standard capture
 PCM device).
 name='Mic Playback Volume',index=0
+----------------------------------
 This control is used to attenuate samples for left and right Mic input.
 For Mic input is used AC97 codec. The result samples are forwarded to 
 the front DAC PCM slots of the Philips DAC. Samples are forwarded to Mic
 capture FIFO (device 1 - 16bit/8KHz mono) too without volume control.
 name='Mic Capture Volume',index=0
+---------------------------------
 This control is used to attenuate samples for left and right Mic input.
 The result is forwarded to the ADC capture FIFO (thus to the standard capture
 PCM device).
 name='Audigy CD Playback Volume',index=0
+----------------------------------------
 This control is used to attenuate samples from left and right IEC958 TTL
 digital inputs (usually used by a CDROM drive). The result samples are
 forwarded to the front DAC PCM slots of the Philips DAC.
 name='Audigy CD Capture Volume',index=0
+---------------------------------------
 This control is used to attenuate samples from left and right IEC958 TTL
 digital inputs (usually used by a CDROM drive). The result samples are
 forwarded to the ADC capture FIFO (thus to the standard capture PCM device).
 name='IEC958 Optical Playback Volume',index=0
+---------------------------------------------
 This control is used to attenuate samples from left and right IEC958 optical
 digital input. The result samples are forwarded to the front DAC PCM slots
 of the Philips DAC.
 name='IEC958 Optical Capture Volume',index=0
+--------------------------------------------
 This control is used to attenuate samples from left and right IEC958 optical
 digital inputs. The result samples are forwarded to the ADC capture FIFO
 (thus to the standard capture PCM device).
 name='Line2 Playback Volume',index=0
+------------------------------------
 This control is used to attenuate samples from left and right I2S ADC
 inputs (on the AudigyDrive). The result samples are forwarded to the front
 DAC PCM slots of the Philips DAC.
 name='Line2 Capture Volume',index=1
+-----------------------------------
 This control is used to attenuate samples from left and right I2S ADC
 inputs (on the AudigyDrive). The result samples are forwarded to the ADC
 capture FIFO (thus to the standard capture PCM device).
 name='Analog Mix Playback Volume',index=0
+-----------------------------------------
 This control is used to attenuate samples from left and right I2S ADC
 inputs from Philips ADC. The result samples are forwarded to the front
 DAC PCM slots of the Philips DAC. This contains mix from analog sources
 like CD, Line In, Aux, ....
 name='Analog Mix Capture Volume',index=1
+----------------------------------------
 This control is used to attenuate samples from left and right I2S ADC
 inputs Philips ADC. The result samples are forwarded to the ADC
 capture FIFO (thus to the standard capture PCM device).
 name='Aux2 Playback Volume',index=0
+-----------------------------------
 This control is used to attenuate samples from left and right I2S ADC
 inputs (on the AudigyDrive). The result samples are forwarded to the front
 DAC PCM slots of the Philips DAC.
 name='Aux2 Capture Volume',index=1
+----------------------------------
 This control is used to attenuate samples from left and right I2S ADC
 inputs (on the AudigyDrive). The result samples are forwarded to the ADC
 capture FIFO (thus to the standard capture PCM device).
 name='Front Playback Volume',index=0
+------------------------------------
 All stereo signals are mixed together and mirrored to surround, center and LFE.
 This control is used to attenuate samples for left and right front speakers of
 this mix.
 name='Surround Playback Volume',index=0
+---------------------------------------
 All stereo signals are mixed together and mirrored to surround, center and LFE.
 This control is used to attenuate samples for left and right surround speakers of
 this mix.
 name='Center Playback Volume',index=0
+-------------------------------------
 All stereo signals are mixed together and mirrored to surround, center and LFE.
 This control is used to attenuate sample for center speaker of this mix.
 name='LFE Playback Volume',index=0
+----------------------------------
 All stereo signals are mixed together and mirrored to surround, center and LFE.
 This control is used to attenuate sample for LFE speaker of this mix.
 name='Tone Control - Switch',index=0
+------------------------------------
 This control turns the tone control on or off. The samples for front, rear
 and center / LFE outputs are affected.
 name='Tone Control - Bass',index=0
+----------------------------------
 This control sets the bass intensity. There is no neutral value!!
 When the tone control code is activated, the samples are always modified.
 The closest value to pure signal is 20.
 name='Tone Control - Treble',index=0
+------------------------------------
 This control sets the treble intensity. There is no neutral value!!
 When the tone control code is activated, the samples are always modified.
 The closest value to pure signal is 20.
 name='Master Playback Volume',index=0
+-------------------------------------
 This control is used to attenuate samples for front, surround, center and 
 LFE outputs.
 name='IEC958 Optical Raw Playback Switch',index=0
+-------------------------------------------------
 If this switch is on, then the samples for the IEC958 (S/PDIF) digital
 output are taken only from the raw FX8010 PCM, otherwise standard front
 PCM samples are taken.
-2) PCM stream related controls
+PCM stream related controls
------------------------------
+===========================
 name='EMU10K1 PCM Volume',index 0-31
+------------------------------------
 Channel volume attenuation in range 0-0xffff. The maximum value (no
 attenuation) is default. The channel mapping for three values is
 as follows:
-	0 - mono, default 0xffff (no attenuation)
+* 0 - mono, default 0xffff (no attenuation)
-	1 - left, default 0xffff (no attenuation)
+* 1 - left, default 0xffff (no attenuation)
-	2 - right, default 0xffff (no attenuation)
+* 2 - right, default 0xffff (no attenuation)
 name='EMU10K1 PCM Send Routing',index 0-31
+------------------------------------------
 This control specifies the destination - FX-bus accumulators. There 24
 values with this mapping:
-	 0 -  mono, A destination (FX-bus 0-63), default 0
+* 0 -  mono, A destination (FX-bus 0-63), default 0
-	 1 -  mono, B destination (FX-bus 0-63), default 1
+* 1 -  mono, B destination (FX-bus 0-63), default 1
-	 2 -  mono, C destination (FX-bus 0-63), default 2
+* 2 -  mono, C destination (FX-bus 0-63), default 2
-	 3 -  mono, D destination (FX-bus 0-63), default 3
+* 3 -  mono, D destination (FX-bus 0-63), default 3
-	 4 -  mono, E destination (FX-bus 0-63), default 0
+* 4 -  mono, E destination (FX-bus 0-63), default 0
-	 5 -  mono, F destination (FX-bus 0-63), default 0
+* 5 -  mono, F destination (FX-bus 0-63), default 0
-	 6 -  mono, G destination (FX-bus 0-63), default 0
+* 6 -  mono, G destination (FX-bus 0-63), default 0
-	 7 -  mono, H destination (FX-bus 0-63), default 0
+* 7 -  mono, H destination (FX-bus 0-63), default 0
-	 8 -  left, A destination (FX-bus 0-63), default 0
+* 8 -  left, A destination (FX-bus 0-63), default 0
-	 9 -  left, B destination (FX-bus 0-63), default 1
+* 9 -  left, B destination (FX-bus 0-63), default 1
-	10 -  left, C destination (FX-bus 0-63), default 2
+* 10 -  left, C destination (FX-bus 0-63), default 2
-	11 -  left, D destination (FX-bus 0-63), default 3
+* 11 -  left, D destination (FX-bus 0-63), default 3
-	12 -  left, E destination (FX-bus 0-63), default 0
+* 12 -  left, E destination (FX-bus 0-63), default 0
-	13 -  left, F destination (FX-bus 0-63), default 0
+* 13 -  left, F destination (FX-bus 0-63), default 0
-	14 -  left, G destination (FX-bus 0-63), default 0
+* 14 -  left, G destination (FX-bus 0-63), default 0
-	15 -  left, H destination (FX-bus 0-63), default 0
+* 15 -  left, H destination (FX-bus 0-63), default 0
-	16 - right, A destination (FX-bus 0-63), default 0
+* 16 - right, A destination (FX-bus 0-63), default 0
-	17 - right, B destination (FX-bus 0-63), default 1
+* 17 - right, B destination (FX-bus 0-63), default 1
-	18 - right, C destination (FX-bus 0-63), default 2
+* 18 - right, C destination (FX-bus 0-63), default 2
-	19 - right, D destination (FX-bus 0-63), default 3
+* 19 - right, D destination (FX-bus 0-63), default 3
-	20 - right, E destination (FX-bus 0-63), default 0
+* 20 - right, E destination (FX-bus 0-63), default 0
-	21 - right, F destination (FX-bus 0-63), default 0
+* 21 - right, F destination (FX-bus 0-63), default 0
-	22 - right, G destination (FX-bus 0-63), default 0
+* 22 - right, G destination (FX-bus 0-63), default 0
-	23 - right, H destination (FX-bus 0-63), default 0
+* 23 - right, H destination (FX-bus 0-63), default 0
 Don't forget that it's illegal to assign a channel to the same FX-bus accumulator 
 more than once (it means 0=0 && 1=0 is an invalid combination).
 name='EMU10K1 PCM Send Volume',index 0-31
+-----------------------------------------
 It specifies the attenuation (amount) for given destination in range 0-255.
 The channel mapping is following:
-	 0 -  mono, A destination attn, default 255 (no attenuation)
+*  0 -  mono, A destination attn, default 255 (no attenuation)
-	 1 -  mono, B destination attn, default 255 (no attenuation)
+*  1 -  mono, B destination attn, default 255 (no attenuation)
-	 2 -  mono, C destination attn, default 0 (mute)
+*  2 -  mono, C destination attn, default 0 (mute)
-	 3 -  mono, D destination attn, default 0 (mute)
+*  3 -  mono, D destination attn, default 0 (mute)
-	 4 -  mono, E destination attn, default 0 (mute)
+*  4 -  mono, E destination attn, default 0 (mute)
-	 5 -  mono, F destination attn, default 0 (mute)
+*  5 -  mono, F destination attn, default 0 (mute)
-	 6 -  mono, G destination attn, default 0 (mute)
+*  6 -  mono, G destination attn, default 0 (mute)
-	 7 -  mono, H destination attn, default 0 (mute)
+*  7 -  mono, H destination attn, default 0 (mute)
-	 8 -  left, A destination attn, default 255 (no attenuation)
+*  8 -  left, A destination attn, default 255 (no attenuation)
-	 9 -  left, B destination attn, default 0 (mute)
+*  9 -  left, B destination attn, default 0 (mute)
-	10 -  left, C destination attn, default 0 (mute)
+* 10 -  left, C destination attn, default 0 (mute)
-	11 -  left, D destination attn, default 0 (mute)
+* 11 -  left, D destination attn, default 0 (mute)
-	12 -  left, E destination attn, default 0 (mute)
+* 12 -  left, E destination attn, default 0 (mute)
-	13 -  left, F destination attn, default 0 (mute)
+* 13 -  left, F destination attn, default 0 (mute)
-	14 -  left, G destination attn, default 0 (mute)
+* 14 -  left, G destination attn, default 0 (mute)
-	15 -  left, H destination attn, default 0 (mute)
+* 15 -  left, H destination attn, default 0 (mute)
-	16 - right, A destination attn, default 0 (mute)
+* 16 - right, A destination attn, default 0 (mute)
-	17 - right, B destination attn, default 255 (no attenuation)
+* 17 - right, B destination attn, default 255 (no attenuation)
-	18 - right, C destination attn, default 0 (mute)
+* 18 - right, C destination attn, default 0 (mute)
-	19 - right, D destination attn, default 0 (mute)
+* 19 - right, D destination attn, default 0 (mute)
-	20 - right, E destination attn, default 0 (mute)
+* 20 - right, E destination attn, default 0 (mute)
-	21 - right, F destination attn, default 0 (mute)
+* 21 - right, F destination attn, default 0 (mute)
-	22 - right, G destination attn, default 0 (mute)
+* 22 - right, G destination attn, default 0 (mute)
-	23 - right, H destination attn, default 0 (mute)
+* 23 - right, H destination attn, default 0 (mute)
-4) MANUALS/PATENTS:
+MANUALS/PATENTS
-------------------
+===============
 ftp://opensource.creative.com/pub/doc
 -------------------------------------
-        Files:
+LM4545.pdf
-        LM4545.pdf      AC97 Codec
+	AC97 Codec
-        m2049.pdf       The EMU10K1 Digital Audio Processor
+m2049.pdf
+	The EMU10K1 Digital Audio Processor
-        hog63.ps        FX8010 - A DSP Chip Architecture for Audio Effects
+hog63.ps
+	FX8010 - A DSP Chip Architecture for Audio Effects
 WIPO Patents
 ------------
-        Patent numbers:
-        WO 9901813 (A1) Audio Effects Processor with multiple asynchronous (Jan. 14, 1999)
-                        streams
-        WO 9901814 (A1) Processor with Instruction Set for Audio Effects (Jan. 14, 1999)
+WO 9901813 (A1)
+	Audio Effects Processor with multiple asynchronous streams
+	(Jan. 14, 1999)
+WO 9901814 (A1)
+	Processor with Instruction Set for Audio Effects (Jan. 14, 1999)
-        WO 9901953 (A1) Audio Effects Processor having Decoupled Instruction
+WO 9901953 (A1)
-                        Execution and Audio Data Sequencing (Jan. 14, 1999)
+	Audio Effects Processor having Decoupled Instruction
+        Execution and Audio Data Sequencing (Jan. 14, 1999)
 US Patents (http://www.uspto.gov/)
 ----------------------------------
-        US 5925841      Digital Sampling Instrument employing cache memory (Jul. 20, 1999)
+US 5925841
+	Digital Sampling Instrument employing cache memory (Jul. 20, 1999)
-        US 5928342      Audio Effects Processor integrated on a single chip (Jul. 27, 1999)
-                        with a multiport memory onto which multiple asynchronous
+US 5928342
-                        digital sound samples can be concurrently loaded
+	Audio Effects Processor integrated on a single chip
+        with a multiport memory onto which multiple asynchronous
-        US 5930158      Processor with Instruction Set for Audio Effects (Jul. 27, 1999)
+        digital sound samples can be concurrently loaded
+	(Jul. 27, 1999)
-        US 6032235      Memory initialization circuit (Tram) (Feb. 29, 2000)
+US 5930158
-        US 6138207      Interpolation looping of audio samples in cache connected to    (Oct. 24, 2000)
+	Processor with Instruction Set for Audio Effects (Jul. 27, 1999)
-                        system bus with prioritization and modification of bus transfers
-                        in accordance with loop ends and minimum block sizes
+US 6032235
+	Memory initialization circuit (Tram) (Feb. 29, 2000)
-        US 6151670      Method for conserving memory storage using a (Nov. 21, 2000)
-                        pool of  short term memory registers
+US 6138207
+	Interpolation looping of audio samples in cache connected to
-        US 6195715      Interrupt control for multiple programs communicating with      (Feb. 27, 2001)
+        system bus with prioritization and modification of bus transfers
-                        a common interrupt by associating programs to GP registers,
+        in accordance with loop ends and minimum block sizes
-                        defining interrupt register, polling GP registers, and invoking
+	(Oct. 24, 2000)
-                        callback routine associated with defined interrupt register
+US 6151670
+	Method for conserving memory storage using a
+        pool of  short term memory registers
+	(Nov. 21, 2000)
+US 6195715
+	Interrupt control for multiple programs communicating with
+        a common interrupt by associating programs to GP registers,
+        defining interrupt register, polling GP registers, and invoking
+        callback routine associated with defined interrupt register
+	(Feb. 27, 2001)
--- a/Documentation/sound/alsa/Audiophile-Usb.txt
+++ b/Documentation/sound/alsa/Audiophile-Usb.txt
-	Guide to using M-Audio Audiophile USB with ALSA and Jack	v1.5
+========================================================
-	========================================================
+Guide to using M-Audio Audiophile USB with ALSA and Jack
+========================================================
-	    Thibault Le Meur <Thibault.LeMeur@supelec.fr>
+v1.5
+Thibault Le Meur <Thibault.LeMeur@supelec.fr>
 This document is a guide to using the M-Audio Audiophile USB (tm) device with 
 ALSA and JACK.
 History
 =======
 * v1.4 - Thibault Le Meur (2007-07-11)
- - Added Low Endianness nature of 16bits-modes
-   found by Hakan Lennestal <Hakan.Lennestal@brfsodrahamn.se>
+  - Added Low Endianness nature of 16bits-modes
- - Modifying document structure
+    found by Hakan Lennestal <Hakan.Lennestal@brfsodrahamn.se>
+  - Modifying document structure
 * v1.5 - Thibault Le Meur (2007-07-12)
- - Added AC3/DTS passthru info
+  - Added AC3/DTS passthru info
-1 - Audiophile USB Specs and correct usage
+Audiophile USB Specs and correct usage
-==========================================
+======================================
 This part is a reminder of important facts about the functions and limitations 
 of the device.
 The device has 4 audio interfaces, and 2 MIDI ports:
 * Analog Stereo Input (Ai)
   - This port supports 2 pairs of line-level audio inputs (1/4" TS and RCA) 
   - When the 1/4" TS (jack) connectors are connected, the RCA connectors
     are disabled
 * Analog Stereo Output (Ao)
 * Digital Stereo Input (Di)
 * Digital Stereo Output (Do)
@@ -34,56 +43,69 @@ The device has 4 audio interfaces, and 2 MIDI ports:
 * Midi Out (Mo)
 The internal DAC/ADC has the following characteristics:
 * sample depth of 16 or 24 bits
 * sample rate from 8kHz to 96kHz
 * Two interfaces can't use different sample depths at the same time.
 Moreover, the Audiophile USB documentation gives the following Warning:
-"Please exit any audio application running before switching between bit depths"
+  Please exit any audio application running before switching between bit depths
 Due to the USB 1.1 bandwidth limitation, a limited number of interfaces can be 
 activated at the same time depending on the audio mode selected:
 * 16-bit/48kHz ==> 4 channels in + 4 channels out
   - Ai+Ao+Di+Do
 * 24-bit/48kHz ==> 4 channels in + 2 channels out, 
-                    or 2 channels in + 4 channels out
+   or 2 channels in + 4 channels out
   - Ai+Ao+Do or Ai+Di+Ao or Ai+Di+Do or Di+Ao+Do
 * 24-bit/96kHz ==> 2 channels in _or_ 2 channels out (half duplex only)
   - Ai or Ao or Di or Do
 Important facts about the Digital interface:
 --------------------------------------------
 * The Do port additionally supports surround-encoded AC-3 and DTS passthrough, 
-though I haven't tested it under Linux
+   though I haven't tested it under Linux
   - Note that in this setup only the Do interface can be enabled
 * Apart from recording an audio digital stream, enabling the Di port is a way 
-to synchronize the device to an external sample clock
+   to synchronize the device to an external sample clock
   - As a consequence, the Di port must be enable only if an active Digital 
-source is connected
+     source is connected
   - Enabling Di when no digital source is connected can result in a 
-synchronization error (for instance sound played at an odd sample rate)
+     synchronization error (for instance sound played at an odd sample rate)
-2 - Audiophile USB MIDI support in ALSA
+Audiophile USB MIDI support in ALSA
-=======================================
+===================================
 The Audiophile USB MIDI ports will be automatically supported once the
 following modules have been loaded:
 * snd-usb-audio
 * snd-seq-midi
 No additional setting is required.
-3 - Audiophile USB Audio support in ALSA
+Audiophile USB Audio support in ALSA
-========================================
+====================================
 Audio functions of the Audiophile USB device are handled by the snd-usb-audio 
 module. This module can work in a default mode (without any device-specific 
 parameter), or in an "advanced" mode with the device-specific parameter called 
-"device_setup".
+``device_setup``.
-3.1 - Default Alsa driver mode
+Default Alsa driver mode
------------------------------
+------------------------
 The default behavior of the snd-usb-audio driver is to list the device 
 capabilities at startup and activate the required mode when required 
@@ -101,6 +123,7 @@ Default Alsa driver mode can lead to device misconfigurations.
 Let's get back to the Default Alsa driver mode for now.  In this case the 
 Audiophile interfaces are mapped to alsa pcm devices in the following 
 way (I suppose the device's index is 1):
 * hw:1,0 is Ao in playback and Di in capture
 * hw:1,1 is Do in playback and Ai in capture
 * hw:1,2 is Do in AC3/DTS passthrough mode
@@ -115,20 +138,28 @@ This has been fixed in kernel 2.6.23 and above and now the hw:1,2 interface
 is reported to be big endian in this default driver mode.
 Examples:
- * playing a S24_3BE encoded raw file to the Ao port
+ * playing a S24_3BE encoded raw file to the Ao port::
   % aplay -D hw:1,0 -c2 -t raw -r48000 -fS24_3BE test.raw
- * recording a  S24_3BE encoded raw file from the Ai port
+ * recording a  S24_3BE encoded raw file from the Ai port::
   % arecord -D hw:1,1 -c2  -t raw -r48000 -fS24_3BE test.raw
- * playing a S16_BE encoded raw file to the Do port
+ * playing a S16_BE encoded raw file to the Do port::
   % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_BE test.raw
- * playing an ac3 sample file to the Do port
+ * playing an ac3 sample file to the Do port::
   % aplay -D hw:1,2 --channels=6 ac3_S16_BE_encoded_file.raw
 If you're happy with the default Alsa driver mode and don't experience any 
 issue with this mode, then you can skip the following chapter.
-3.2 - Advanced module setup
+Advanced module setup
---------------------------
+---------------------
 Due to the hardware constraints described above, the device initialization made 
 by the Alsa driver in default mode may result in a corrupted state of the 
@@ -137,34 +168,39 @@ from the Ai interface sounds distorted (as if boosted with an excessive high
 volume gain).
 For people having this problem, the snd-usb-audio module has a new module 
-parameter called "device_setup" (this parameter was introduced in kernel
+parameter called ``device_setup`` (this parameter was introduced in kernel
 release 2.6.17)
-3.2.1 - Initializing the working mode of the Audiophile USB
+Initializing the working mode of the Audiophile USB
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 As far as the Audiophile USB device is concerned, this value let the user 
 specify:
 * the sample depth
 * the sample rate
 * whether the Di port is used or not 
-When initialized with "device_setup=0x00", the snd-usb-audio module has
+When initialized with ``device_setup=0x00``, the snd-usb-audio module has
 the same behaviour as when the parameter is omitted (see paragraph "Default 
 Alsa driver mode" above)
 Others modes are described in the following subsections.
-3.2.1.1 - 16-bit modes
+16-bit modes
+~~~~~~~~~~~~
 The two supported modes are:
- * device_setup=0x01
+ * ``device_setup=0x01``
   - 16bits 48kHz mode with Di disabled
   - Ai,Ao,Do can be used at the same time
   - hw:1,0 is not available in capture mode
   - hw:1,2 is not available
- * device_setup=0x11
+ * ``device_setup=0x11``
   - 16bits 48kHz mode with Di enabled
   - Ai,Ao,Di,Do can be used at the same time
   - hw:1,0 is available in capture mode
@@ -173,33 +209,43 @@ The two supported modes are:
 In this modes the device operates only at 16bits-modes. Before kernel 2.6.23,
 the devices where reported to be Big-Endian when in fact they were Little-Endian
 so that playing a file was a matter of using:
+::
   % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_BE test_S16_LE.raw
 where "test_S16_LE.raw" was in fact a little-endian sample file.
 Thanks to Hakan Lennestal (who discovered the Little-Endiannes of the device in
 these modes) a fix has been committed (expected in kernel 2.6.23) and
 Alsa now reports Little-Endian interfaces. Thus playing a file now is as simple as
 using:
+::
   % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_LE test_S16_LE.raw
-3.2.1.2 - 24-bit modes
+24-bit modes
+~~~~~~~~~~~~
 The three supported modes are:
- * device_setup=0x09
+ * ``device_setup=0x09``
   - 24bits 48kHz mode with Di disabled
   - Ai,Ao,Do can be used at the same time
   - hw:1,0 is not available in capture mode
   - hw:1,2 is not available
- * device_setup=0x19
+ * ``device_setup=0x19``
   - 24bits 48kHz mode with Di enabled
   - 3 ports from {Ai,Ao,Di,Do} can be used at the same time
   - hw:1,0 is available in capture mode and an active digital source must be 
     connected to Di
   - hw:1,2 is not available
- * device_setup=0x0D or 0x10
+ * ``device_setup=0x0D`` or ``0x10``
   - 24bits 96kHz mode
   - Di is enabled by default for this mode but does not need to be connected 
     to an active source
@@ -210,29 +256,35 @@ The three supported modes are:
 In these modes the device is only Big-Endian compliant (see "Default Alsa driver 
 mode" above for an aplay command example)
-3.2.1.3 - AC3 w/ DTS passthru mode
+AC3 w/ DTS passthru mode
+~~~~~~~~~~~~~~~~~~~~~~~~
 Thanks to Hakan Lennestal, I now have a report saying that this mode works.
- * device_setup=0x03
+ * ``device_setup=0x03``
   - 16bits 48kHz mode with only the Do port enabled 
   - AC3 with DTS passthru
   - Caution with this setup the Do port is mapped to the pcm device hw:1,0
 The command line used to playback the AC3/DTS encoded .wav-files in this mode:
+::
   % aplay -D hw:1,0 --channels=6 ac3_S16_LE_encoded_file.raw
-3.2.2 - How to use the device_setup parameter
+How to use the ``device_setup`` parameter
----------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The parameter can be given:
- * By manually probing the device (as root):
+ * By manually probing the device (as root):::
   # modprobe -r snd-usb-audio
   # modprobe snd-usb-audio index=1 device_setup=0x09
 * Or while configuring the modules options in your modules configuration file
-   (typically a .conf file in /etc/modprobe.d/ directory:
+   (typically a .conf file in /etc/modprobe.d/ directory:::
       alias snd-card-1 snd-usb-audio
       options snd-usb-audio index=1 device_setup=0x09
@@ -250,26 +302,31 @@ CAUTION when initializing the device
 * If you've correctly initialized the device in a valid mode and then want to switch
   to  another mode (possibly with another sample-depth), please use also the following 
   procedure:
   - first turn off the device
   - de-register the snd-usb-audio module (modprobe -r)
   - change the device_setup parameter by changing the device_setup
-     option in /etc/modprobe.d/*.conf
+     option in ``/etc/modprobe.d/*.conf``
   - turn on the device
 * A workaround for this last issue has been applied to kernel 2.6.23, but it may not
   be enough to ensure the 'stability' of the device initialization.
-3.2.3 - Technical details for hackers
+Technical details for hackers
-------------------------------------
+-----------------------------
 This section is for hackers, wanting to understand details about the device
 internals and how Alsa supports it.
-3.2.3.1 - Audiophile USB's device_setup structure
+Audiophile USB's ``device_setup`` structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If you want to understand the device_setup magic numbers for the Audiophile 
 USB, you need some very basic understanding of binary computation. However, 
 this is not required to use the parameter and you may skip this section.
 The device_setup is one byte long and its structure is the following:
+::
       +---+---+---+---+---+---+---+---+
       | b7| b6| b5| b4| b3| b2| b1| b0|
@@ -278,38 +335,55 @@ The device_setup is one byte long and its structure is the following:
       +---+---+---+---+---+---+---+---+
 Where:
- * b0 is the "SET" bit
+ * b0 is the ``SET`` bit
   - it MUST be set if device_setup is initialized 
- * b1 is the "DTS" bit
+ * b1 is the ``DTS`` bit
   - it is set only for Digital output with DTS/AC3
   - this setup is not tested
 * b2 is the Rate selection flag
-   - When set to "1" the rate range is 48.1-96kHz
+   - When set to ``1`` the rate range is 48.1-96kHz
   - Otherwise the sample rate range is 8-48kHz
 * b3 is the bit depth selection flag
-   - When set to "1" samples are 24bits long
+   - When set to ``1`` samples are 24bits long
   - Otherwise they are 16bits long
   - Note that b2 implies b3 as the 96kHz mode is only supported for 24 bits 
     samples
 * b4 is the Digital input flag
-   - When set to "1" the device assumes that an active digital source is 
+   - When set to ``1`` the device assumes that an active digital source is 
     connected 
   - You shouldn't enable Di if no source is seen on the port (this leads to 
     synchronization issues)
   - b4 is implied by b2 (since only one port is enabled at a time no synch 
     error can occur) 
- * b5 to b7 are reserved for future uses, and must be set to "0"
+ * b5 to b7 are reserved for future uses, and must be set to ``0``
   - might become Ao, Do, Ai, for b7, b6, b4 respectively
 Caution:
 * there is no check on the value you will give to device_setup
   - for instance choosing 0x05 (16bits 96kHz) will fail back to 0x09 since 
     b2 implies b3. But _there_will_be_no_warning_ in /var/log/messages
 * Hardware constraints due to the USB bus limitation aren't checked
   - choosing b2 will prepare all interfaces for 24bits/96kHz but you'll
     only be able to use one at the same time
-3.2.3.2 -  USB implementation details for this device
+USB implementation details for this device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 You may safely skip this section if you're not interested in driver 
 hacking.
@@ -319,46 +393,72 @@ data I got by usb-snooping the windows and Linux drivers.
 The M-Audio Audiophile USB has 7 USB Interfaces:
 a "USB interface":
 * USB Interface nb.0
 * USB Interface nb.1
   - Audio Control function
 * USB Interface nb.2
   - Analog Output
 * USB Interface nb.3
   - Digital Output
 * USB Interface nb.4
   - Analog Input
 * USB Interface nb.5
   - Digital Input
 * USB Interface nb.6
   - MIDI interface compliant with the MIDIMAN quirk 
 Each interface has 5 altsettings (AltSet 1,2,3,4,5) except:
 * Interface 3 (Digital Out) has an extra Alset nb.6 
 * Interface 5 (Digital In) does not have Alset nb.3 and 5 
 Here is a short description of the AltSettings capabilities:
- * AltSettings 1 corresponds to
+* AltSettings 1 corresponds to
  - 24-bit depth, 48.1-96kHz sample mode
  - Adaptive playback (Ao and Do), Synch capture (Ai), or Asynch capture (Di)
- * AltSettings 2 corresponds to
+* AltSettings 2 corresponds to
  - 24-bit depth, 8-48kHz sample mode
  - Asynch capture and playback  (Ao,Ai,Do,Di)
- * AltSettings 3 corresponds to
+* AltSettings 3 corresponds to
  - 24-bit depth, 8-48kHz sample mode
  - Synch capture (Ai) and Adaptive playback (Ao,Do)
- * AltSettings 4 corresponds to
+* AltSettings 4 corresponds to
  - 16-bit depth, 8-48kHz sample mode
  - Asynch capture and playback  (Ao,Ai,Do,Di)
- * AltSettings 5 corresponds to
+* AltSettings 5 corresponds to
  - 16-bit depth, 8-48kHz sample mode
  - Synch capture (Ai) and Adaptive playback (Ao,Do)
- * AltSettings 6 corresponds to
+* AltSettings 6 corresponds to
  - 16-bit depth, 8-48kHz sample mode
  - Synch playback (Do), audio format type III IEC1937_AC-3
 In order to ensure a correct initialization of the device, the driver 
-_must_know_ how the device will be used:
+*must* *know* how the device will be used:
 * if DTS is chosen, only Interface 2 with AltSet nb.6 must be
   registered
 * if 96KHz only AltSets nb.1 of each interface must be selected
@@ -371,20 +471,21 @@ _must_know_ how the device will be used:
 When device_setup is given as a parameter to the snd-usb-audio module, the 
 parse_audio_endpoints function uses a quirk called 
-"audiophile_skip_setting_quirk" in order to prevent AltSettings not 
+``audiophile_skip_setting_quirk`` in order to prevent AltSettings not 
 corresponding to device_setup from being registered in the driver.
-4 - Audiophile USB and Jack support
+Audiophile USB and Jack support
-===================================
+===============================
 This section deals with support of the Audiophile USB device in Jack.
 There are 2 main potential issues when using Jackd with the device:
 * support for Big-Endian devices in 24-bit modes
 * support for 4-in / 4-out channels
-4.1 - Direct support in Jackd
+Direct support in Jackd
-----------------------------
+-----------------------
 Jack supports big endian devices only in recent versions (thanks to
 Andreas Steinmetz for his first big-endian patch). I can't remember 
@@ -396,29 +497,35 @@ are now Little Endians ;-) ).
 You can run jackd with the following command for playback with Ao and
 record with Ai:
+::
  % jackd -R -dalsa -Phw:1,0 -r48000 -p128 -n2 -D -Chw:1,1
-4.2 - Using Alsa plughw
+Using Alsa plughw
-----------------------
+-----------------
 If you don't have a recent Jackd installed, you can downgrade to using
-the Alsa "plug" converter.
+the Alsa ``plug`` converter.
 For instance here is one way to run Jack with 2 playback channels on Ao and 2 
 capture channels from Ai:
+::
  % jackd -R -dalsa -dplughw:1 -r48000 -p256 -n2 -D -Cplughw:1,1
 However you may see the following warning message:
-"You appear to be using the ALSA software "plug" layer, probably a result of 
+  You appear to be using the ALSA software "plug" layer, probably a result of 
-using the "default" ALSA device. This is less efficient than it could be. 
+  using the "default" ALSA device. This is less efficient than it could be. 
-Consider using a hardware device instead rather than using the plug layer."
+  Consider using a hardware device instead rather than using the plug layer.
-4.3 - Getting 2 input and/or output interfaces in Jack
+Getting 2 input and/or output interfaces in Jack
------------------------------------------------------
+------------------------------------------------
 As you can see, starting the Jack server this way will only enable 1 stereo
 input (Di or Ai) and 1 stereo output (Ao or Do).
 This is due to the following restrictions:
 * Jack can only open one capture device and one playback device at a time
 * The Audiophile USB is seen as 2 (or three) Alsa devices: hw:1,0, hw:1,1
  (and optionally hw:1,2)
@@ -432,6 +539,7 @@ It is related to another device (ice1712) but can be adapted to suit
 the Audiophile USB.
 Enabling multiple Audiophile USB interfaces for Jackd will certainly require:
 * Making sure your Jackd version has the MMAP_COMPLEX patch (see the ice1712 page)
 * (maybe) patching the alsa-lib/src/pcm/pcm_multi.c file (see the ice1712 page)
 * define a multi device (combination of hw:1,0 and hw:1,1) in your .asoundrc

--- a/Documentation/sound/alsa/Bt87x.txt
+++ b/Documentation/sound/alsa/Bt87x.txt
+=================
+ALSA BT87x Driver
+=================
 Intro
 =====
 You might have noticed that the bt878 grabber cards have actually
-_two_ PCI functions:
+*two* PCI functions:
+::
-$ lspci
+  $ lspci
-[ ... ]
+  [ ... ]
-00:0a.0 Multimedia video controller: Brooktree Corporation Bt878 (rev 02)
+  00:0a.0 Multimedia video controller: Brooktree Corporation Bt878 (rev 02)
-00:0a.1 Multimedia controller: Brooktree Corporation Bt878 (rev 02)
+  00:0a.1 Multimedia controller: Brooktree Corporation Bt878 (rev 02)
-[ ... ]
+  [ ... ]
 The first does video, it is backward compatible to the bt848.  The second
 does audio.  snd-bt87x is a driver for the second function.  It's a sound
-driver which can be used for recording sound (and _only_ recording, no
+driver which can be used for recording sound (and *only* recording, no
 playback).  As most TV cards come with a short cable which can be plugged
 into your sound card's line-in you probably don't need this driver if all
 you want to do is just watching TV...
@@ -30,9 +35,9 @@ The driver is now stable.  However, it doesn't know about many TV cards,
 and it refuses to load for cards it doesn't know.
 If the driver complains ("Unknown TV card found, the audio driver will
-not load"), you can specify the load_all=1 option to force the driver to
+not load"), you can specify the ``load_all=1`` option to force the driver to
 try to use the audio capture function of your card.  If the frequency of
-recorded data is not right, try to specify the digital_rate option with
+recorded data is not right, try to specify the ``digital_rate`` option with
 other values than the default 32000 (often it's 44100 or 64000).
 If you have an unknown card, please mail the ID and board name to

--- a/Documentation/sound/alsa/CMIPCI.txt
+++ b/Documentation/sound/alsa/CMIPCI.txt
--- a/Documentation/sound/alsa/emu10k1-jack.txt
+++ b/Documentation/sound/alsa/emu10k1-jack.txt
+=================================================================
+Low latency, multichannel audio with JACK and the emu10k1/emu10k2
+=================================================================
 This document is a guide to using the emu10k1 based devices with JACK for low
 latency, multichannel recording functionality.  All of my recent work to allow
 Linux users to use the full capabilities of their hardware has been inspired 
@@ -7,8 +11,6 @@ power of this hardware.
 	http://www.kxproject.com
 						- Lee Revell, 2005.03.30
-Low latency, multichannel audio with JACK and the emu10k1/emu10k2
-----------------------------------------------------------------
 Until recently, emu10k1 users on Linux did not have access to the same low
 latency, multichannel features offered by the "kX ASIO" feature of their
@@ -23,14 +25,15 @@ select the correct device for JACK to use.  Actually, for qjackctl users it's
 fairly self explanatory - select Duplex, then for capture and playback select
 the multichannel devices, set the in and out channels to 16, and the sample
 rate to 48000Hz.  The command line looks like this:
+::
-/usr/local/bin/jackd -R -dalsa -r48000 -p64 -n2 -D -Chw:0,2 -Phw:0,3 -S
+  /usr/local/bin/jackd -R -dalsa -r48000 -p64 -n2 -D -Chw:0,2 -Phw:0,3 -S
 This will give you 16 input ports and 16 output ports.
 The 16 output ports map onto the 16 FX buses (or the first 16 of 64, for the
 Audigy).  The mapping from FX bus to physical output is described in
-SB-Live-mixer.txt (or Audigy-mixer.txt).
+sb-live-mixer.rst (or audigy-mixer.rst).
 The 16 input ports are connected to the 16 physical inputs.  Contrary to
 popular belief, all emu10k1 cards are multichannel cards.  Which of these
@@ -49,10 +52,11 @@ This chart, borrowed from kxfxlib/da_asio51.cpp, describes the mapping of JACK
 ports to FXBUS2 (multitrack recording input) and EXTOUT (physical output)
 channels.
-/*JACK (& ASIO) mappings on 10k1 5.1 SBLive cards:
+JACK (& ASIO) mappings on 10k1 5.1 SBLive cards:
--------------------------------------------
+==============  ========        ============
 JACK		Epilog		FXBUS2(nr)
--------------------------------------------
+==============  ========        ============
 capture_1	asio14		FXBUS2(0xe)
 capture_2	asio15		FXBUS2(0xf)
 capture_3	asio0		FXBUS2(0x0)	
@@ -69,6 +73,6 @@ capture_13	asio10		FXBUS2(0xa)
 capture_14	asio11		FXBUS2(0xb)
 capture_15	asio12		FXBUS2(0xc)
 capture_16	asio13		FXBUS2(0xd)
-*/
+==============  ========        ============
 TODO: describe use of ld10k1/qlo10k1 in conjunction with JACK
--- a/Documentation/sound/alsa/hdspm.txt
+++ b/Documentation/sound/alsa/hdspm.txt
--- a/Documentation/sound/alsa/img,spdif-in.txt
+++ b/Documentation/sound/alsa/img,spdif-in.txt
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
+Card-Specific Information
+=========================
+.. toctree::
+   :maxdepth: 2
+   joystick
+   cmipci
+   sb-live-mixer
+   audigy-mixer
+   emu10k1-jack
+   via82xx-mixer
+   audiophile-usb
+   mixart
+   bt87x
+   maya44
+   hdspm
+   serial-u16550
+   img-spdif-in
--- a/Documentation/sound/alsa/Joystick.txt
+++ b/Documentation/sound/alsa/Joystick.txt
--- a/Documentation/sound/alsa/README.maya44
+++ b/Documentation/sound/alsa/README.maya44
--- a/Documentation/sound/alsa/MIXART.txt
+++ b/Documentation/sound/alsa/MIXART.txt
--- a/Documentation/sound/alsa/SB-Live-mixer.txt
+++ b/Documentation/sound/alsa/SB-Live-mixer.txt
--- a/Documentation/sound/alsa/serial-u16550.txt
+++ b/Documentation/sound/alsa/serial-u16550.txt
--- a/Documentation/sound/cards/via82xx-mixer.rst
+++ b/Documentation/sound/cards/via82xx-mixer.rst
+=============
+VIA82xx mixer
+=============
+On many VIA82xx boards, the ``Input Source Select`` mixer control does not work.
+Setting it to ``Input2`` on such boards will cause recording to hang, or fail
+with EIO (input/output error) via OSS emulation.  This control should be left
+at ``Input1`` for such cards.
--- a/Documentation/sound/alsa/Channel-Mapping-API.txt
+++ b/Documentation/sound/alsa/Channel-Mapping-API.txt
--- a/Documentation/sound/alsa/compress_offload.txt
+++ b/Documentation/sound/alsa/compress_offload.txt
--- a/Documentation/sound/designs/control-names.rst
+++ b/Documentation/sound/designs/control-names.rst
--- a/Documentation/sound/designs/index.rst
+++ b/Documentation/sound/designs/index.rst
--- a/Documentation/sound/alsa/Jack-Controls.txt
+++ b/Documentation/sound/alsa/Jack-Controls.txt
--- a/Documentation/sound/alsa/OSS-Emulation.txt
+++ b/Documentation/sound/alsa/OSS-Emulation.txt
--- a/Documentation/sound/alsa/powersave.txt
+++ b/Documentation/sound/alsa/powersave.txt
--- a/Documentation/sound/alsa/Procfile.txt
+++ b/Documentation/sound/alsa/Procfile.txt
--- a/Documentation/sound/designs/seq-oss.rst
+++ b/Documentation/sound/designs/seq-oss.rst
--- a/Documentation/sound/alsa/timestamping.txt
+++ b/Documentation/sound/alsa/timestamping.txt
--- a/Documentation/sound/alsa/HD-Audio-Controls.txt
+++ b/Documentation/sound/alsa/HD-Audio-Controls.txt
--- a/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt
+++ b/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt
--- a/Documentation/sound/hd-audio/index.rst
+++ b/Documentation/sound/hd-audio/index.rst
--- a/Documentation/sound/hd-audio/models.rst
+++ b/Documentation/sound/hd-audio/models.rst
--- a/Documentation/sound/alsa/HD-Audio.txt
+++ b/Documentation/sound/alsa/HD-Audio.txt
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
--- a/Documentation/sound/kernel-api/alsa-driver-api.rst
+++ b/Documentation/sound/kernel-api/alsa-driver-api.rst
--- a/Documentation/sound/kernel-api/index.rst
+++ b/Documentation/sound/kernel-api/index.rst
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
--- a/Documentation/sound/alsa/soc/clocking.txt
+++ b/Documentation/sound/alsa/soc/clocking.txt
--- a/Documentation/sound/soc/codec-to-codec.rst
+++ b/Documentation/sound/soc/codec-to-codec.rst
--- a/Documentation/sound/alsa/soc/codec.txt
+++ b/Documentation/sound/alsa/soc/codec.txt
--- a/Documentation/sound/alsa/soc/DAI.txt
+++ b/Documentation/sound/alsa/soc/DAI.txt
--- a/Documentation/sound/alsa/soc/dapm.txt
+++ b/Documentation/sound/alsa/soc/dapm.txt
--- a/Documentation/sound/alsa/soc/DPCM.txt
+++ b/Documentation/sound/alsa/soc/DPCM.txt
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
--- a/Documentation/sound/alsa/soc/jack.txt
+++ b/Documentation/sound/alsa/soc/jack.txt
--- a/Documentation/sound/alsa/soc/machine.txt
+++ b/Documentation/sound/alsa/soc/machine.txt
--- a/Documentation/sound/alsa/soc/overview.txt
+++ b/Documentation/sound/alsa/soc/overview.txt
--- a/Documentation/sound/alsa/soc/platform.txt
+++ b/Documentation/sound/alsa/soc/platform.txt
--- a/Documentation/sound/alsa/soc/pops_clicks.txt
+++ b/Documentation/sound/alsa/soc/pops_clicks.txt