summaryrefslogtreecommitdiffstats
path: root/Documentation/sound
diff options
context:
space:
mode:
authorTimothy Pearson <tpearson@raptorengineering.com>2017-08-23 14:45:25 -0500
committerTimothy Pearson <tpearson@raptorengineering.com>2017-08-23 14:45:25 -0500
commitfcbb27b0ec6dcbc5a5108cb8fb19eae64593d204 (patch)
tree22962a4387943edc841c72a4e636a068c66d58fd /Documentation/sound
downloadast2050-linux-kernel-fcbb27b0ec6dcbc5a5108cb8fb19eae64593d204.zip
ast2050-linux-kernel-fcbb27b0ec6dcbc5a5108cb8fb19eae64593d204.tar.gz
Initial import of modified Linux 2.6.28 tree
Original upstream URL: git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git | branch linux-2.6.28.y
Diffstat (limited to 'Documentation/sound')
-rw-r--r--Documentation/sound/alsa/ALSA-Configuration.txt2417
-rw-r--r--Documentation/sound/alsa/Audigy-mixer.txt345
-rw-r--r--Documentation/sound/alsa/Audiophile-Usb.txt442
-rw-r--r--Documentation/sound/alsa/Bt87x.txt78
-rw-r--r--Documentation/sound/alsa/CMIPCI.txt254
-rw-r--r--Documentation/sound/alsa/ControlNames.txt84
-rw-r--r--Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl100
-rw-r--r--Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl6210
-rw-r--r--Documentation/sound/alsa/Joystick.txt86
-rw-r--r--Documentation/sound/alsa/MIXART.txt100
-rw-r--r--Documentation/sound/alsa/OSS-Emulation.txt305
-rw-r--r--Documentation/sound/alsa/Procfile.txt207
-rw-r--r--Documentation/sound/alsa/SB-Live-mixer.txt356
-rw-r--r--Documentation/sound/alsa/VIA82xx-mixer.txt8
-rw-r--r--Documentation/sound/alsa/emu10k1-jack.txt74
-rw-r--r--Documentation/sound/alsa/hda_codec.txt322
-rw-r--r--Documentation/sound/alsa/hdspm.txt362
-rw-r--r--Documentation/sound/alsa/powersave.txt41
-rw-r--r--Documentation/sound/alsa/seq_oss.html409
-rw-r--r--Documentation/sound/alsa/serial-u16550.txt88
-rw-r--r--Documentation/sound/alsa/soc/DAI.txt56
-rw-r--r--Documentation/sound/alsa/soc/clocking.txt51
-rw-r--r--Documentation/sound/alsa/soc/codec.txt198
-rw-r--r--Documentation/sound/alsa/soc/dapm.txt290
-rw-r--r--Documentation/sound/alsa/soc/machine.txt113
-rw-r--r--Documentation/sound/alsa/soc/overview.txt86
-rw-r--r--Documentation/sound/alsa/soc/platform.txt58
-rw-r--r--Documentation/sound/alsa/soc/pops_clicks.txt52
-rw-r--r--Documentation/sound/oss/ALS66
-rw-r--r--Documentation/sound/oss/AudioExcelDSP16101
-rw-r--r--Documentation/sound/oss/CMI8330153
-rw-r--r--Documentation/sound/oss/CS423223
-rw-r--r--Documentation/sound/oss/ESS34
-rw-r--r--Documentation/sound/oss/ESS186855
-rw-r--r--Documentation/sound/oss/Introduction459
-rw-r--r--Documentation/sound/oss/MultiSound1137
-rw-r--r--Documentation/sound/oss/OPL36
-rw-r--r--Documentation/sound/oss/Opti222
-rw-r--r--Documentation/sound/oss/PAS16163
-rw-r--r--Documentation/sound/oss/PSS41
-rw-r--r--Documentation/sound/oss/PSS-updates88
-rw-r--r--Documentation/sound/oss/README.OSS1456
-rw-r--r--Documentation/sound/oss/README.modules106
-rw-r--r--Documentation/sound/oss/README.ymfsb107
-rw-r--r--Documentation/sound/oss/SoundPro105
-rw-r--r--Documentation/sound/oss/Soundblaster53
-rw-r--r--Documentation/sound/oss/Tropez+26
-rw-r--r--Documentation/sound/oss/VIBRA1680
-rw-r--r--Documentation/sound/oss/WaveArtist170
-rw-r--r--Documentation/sound/oss/btaudio92
-rw-r--r--Documentation/sound/oss/mwave185
-rw-r--r--Documentation/sound/oss/ultrasound30
-rw-r--r--Documentation/sound/oss/vwsnd293
53 files changed, 18443 insertions, 0 deletions
diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt
new file mode 100644
index 0000000..bef6550
--- /dev/null
+++ b/Documentation/sound/alsa/ALSA-Configuration.txt
@@ -0,0 +1,2417 @@
+
+ Advanced Linux Sound Architecture - Driver
+ ==========================================
+ Configuration guide
+
+
+Kernel Configuration
+====================
+
+To enable ALSA support you need at least to build the kernel with
+primary sound card support (CONFIG_SOUND). Since ALSA can emulate OSS,
+you don't have to choose any of the OSS modules.
+
+Enable "OSS API emulation" (CONFIG_SND_OSSEMUL) and both OSS mixer and
+PCM supports if you want to run OSS applications with ALSA.
+
+If you want to support the WaveTable functionality on cards such as
+SB Live! then you need to enable "Sequencer support"
+(CONFIG_SND_SEQUENCER).
+
+To make ALSA debug messages more verbose, enable the "Verbose printk"
+and "Debug" options. To check for memory leaks, turn on "Debug memory"
+too. "Debug detection" will add checks for the detection of cards.
+
+Please note that all the ALSA ISA drivers support the Linux isapnp API
+(if the card supports ISA PnP). You don't need to configure the cards
+using isapnptools.
+
+
+Creating ALSA devices
+=====================
+
+This depends on your distribution, but normally you use the /dev/MAKEDEV
+script to create the necessary device nodes. On some systems you use a
+script named 'snddevices'.
+
+
+Module parameters
+=================
+
+The user can load modules with options. If the module supports more than
+one card and you have more than one card of the same type then you can
+specify multiple values for the option separated by commas.
+
+Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
+
+ Module snd
+ ----------
+
+ The core ALSA module. It is used by all ALSA card drivers.
+ It takes the following options which have global effects.
+
+ major - major number for sound driver
+ - Default: 116
+ cards_limit
+ - limiting card index for auto-loading (1-8)
+ - Default: 1
+ - For auto-loading more than one card, specify this
+ option together with snd-card-X aliases.
+ slots - Reserve the slot index for the given driver.
+ This option takes multiple strings.
+ See "Module Autoloading Support" section for details.
+
+ Module snd-pcm-oss
+ ------------------
+
+ The PCM OSS emulation module.
+ This module takes options which change the mapping of devices.
+
+ dsp_map - PCM device number maps assigned to the 1st OSS device.
+ - Default: 0
+ adsp_map - PCM device number maps assigned to the 2st OSS device.
+ - Default: 1
+ nonblock_open
+ - Don't block opening busy PCM devices. Default: 1
+
+ For example, when dsp_map=2, /dev/dsp will be mapped to PCM #2 of
+ the card #0. Similarly, when adsp_map=0, /dev/adsp will be mapped
+ to PCM #0 of the card #0.
+ For changing the second or later card, specify the option with
+ commas, such like "dsp_map=0,1".
+
+ nonblock_open option is used to change the behavior of the PCM
+ regarding opening the device. When this option is non-zero,
+ opening a busy OSS PCM device won't be blocked but return
+ immediately with EAGAIN (just like O_NONBLOCK flag).
+
+ Module snd-rawmidi
+ ------------------
+
+ This module takes options which change the mapping of devices.
+ similar to those of the snd-pcm-oss module.
+
+ midi_map - MIDI device number maps assigned to the 1st OSS device.
+ - Default: 0
+ amidi_map - MIDI device number maps assigned to the 2st OSS device.
+ - Default: 1
+
+ Common parameters for top sound card modules
+ --------------------------------------------
+
+ Each of top level sound card module takes the following options.
+
+ index - index (slot #) of sound card
+ - Values: 0 through 31 or negative
+ - If nonnegative, assign that index number
+ - if negative, interpret as a bitmask of permissible
+ indices; the first free permitted index is assigned
+ - Default: -1
+ id - card ID (identifier or name)
+ - Can be up to 15 characters long
+ - Default: the card type
+ - A directory by this name is created under /proc/asound/
+ containing information about the card
+ - This ID can be used instead of the index number in
+ identifying the card
+ enable - enable card
+ - Default: enabled, for PCI and ISA PnP cards
+
+ Module snd-adlib
+ ----------------
+
+ Module for AdLib FM cards.
+
+ port - port # for OPL chip
+
+ This module supports multiple cards. It does not support autoprobe, so
+ the port must be specified. For actual AdLib FM cards it will be 0x388.
+ Note that this card does not have PCM support and no mixer; only FM
+ synthesis.
+
+ Make sure you have "sbiload" from the alsa-tools package available and,
+ after loading the module, find out the assigned ALSA sequencer port
+ number through "sbiload -l". Example output:
+
+ Port Client name Port name
+ 64:0 OPL2 FM synth OPL2 FM Port
+
+ Load the std.sb and drums.sb patches also supplied by sbiload:
+
+ sbiload -p 64:0 std.sb drums.sb
+
+ If you use this driver to drive an OPL3, you can use std.o3 and drums.o3
+ instead. To have the card produce sound, use aplaymidi from alsa-utils:
+
+ aplaymidi -p 64:0 foo.mid
+
+ Module snd-ad1816a
+ ------------------
+
+ Module for sound cards based on Analog Devices AD1816A/AD1815 ISA chips.
+
+ clockfreq - Clock frequency for AD1816A chip (default = 0, 33000Hz)
+
+ This module supports multiple cards, autoprobe and PnP.
+
+ Module snd-ad1848
+ -----------------
+
+ Module for sound cards based on AD1848/AD1847/CS4248 ISA chips.
+
+ port - port # for AD1848 chip
+ irq - IRQ # for AD1848 chip
+ dma1 - DMA # for AD1848 chip (0,1,3)
+
+ This module supports multiple cards. It does not support autoprobe
+ thus main port must be specified!!! Other ports are optional.
+
+ The power-management is supported.
+
+ Module snd-ad1889
+ -----------------
+
+ Module for Analog Devices AD1889 chips.
+
+ ac97_quirk - AC'97 workaround for strange hardware
+ See the description of intel8x0 module for details.
+
+ This module supports multiple cards.
+
+ Module snd-ali5451
+ ------------------
+
+ Module for ALi M5451 PCI chip.
+
+ pcm_channels - Number of hardware channels assigned for PCM
+ spdif - Support SPDIF I/O
+ - Default: disabled
+
+ This module supports one chip and autoprobe.
+
+ The power-management is supported.
+
+ Module snd-als100
+ -----------------
+
+ Module for sound cards based on Avance Logic ALS100/ALS120 ISA chips.
+
+ This module supports multiple cards, autoprobe and PnP.
+
+ The power-management is supported.
+
+ Module snd-als300
+ -----------------
+
+ Module for Avance Logic ALS300 and ALS300+
+
+ This module supports multiple cards.
+
+ The power-management is supported.
+
+ Module snd-als4000
+ ------------------
+
+ Module for sound cards based on Avance Logic ALS4000 PCI chip.
+
+ joystick_port - port # for legacy joystick support.
+ 0 = disabled (default), 1 = auto-detect
+
+ This module supports multiple cards, autoprobe and PnP.
+
+ The power-management is supported.
+
+ Module snd-atiixp
+ -----------------
+
+ Module for ATI IXP 150/200/250/400 AC97 controllers.
+
+ ac97_clock - AC'97 clock (default = 48000)
+ ac97_quirk - AC'97 workaround for strange hardware
+ See "AC97 Quirk Option" section below.
+ ac97_codec - Workaround to specify which AC'97 codec
+ instead of probing. If this works for you
+ file a bug with your `lspci -vn` output.
+ -2 -- Force probing.
+ -1 -- Default behavior.
+ 0-2 -- Use the specified codec.
+ spdif_aclink - S/PDIF transfer over AC-link (default = 1)
+
+ This module supports one card and autoprobe.
+
+ ATI IXP has two different methods to control SPDIF output. One is
+ over AC-link and another is over the "direct" SPDIF output. The
+ implementation depends on the motherboard, and you'll need to
+ choose the correct one via spdif_aclink module option.
+
+ The power-management is supported.
+
+ Module snd-atiixp-modem
+ -----------------------
+
+ Module for ATI IXP 150/200/250 AC97 modem controllers.
+
+ This module supports one card and autoprobe.
+
+ Note: The default index value of this module is -2, i.e. the first
+ slot is excluded.
+
+ The power-management is supported.
+
+ Module snd-au8810, snd-au8820, snd-au8830
+ -----------------------------------------
+
+ Module for Aureal Vortex, Vortex2 and Advantage device.
+
+ pcifix - Control PCI workarounds
+ 0 = Disable all workarounds
+ 1 = Force the PCI latency of the Aureal card to 0xff
+ 2 = Force the Extend PCI#2 Internal Master for Efficient
+ Handling of Dummy Requests on the VIA KT133 AGP Bridge
+ 3 = Force both settings
+ 255 = Autodetect what is required (default)
+
+ This module supports all ADB PCM channels, ac97 mixer, SPDIF, hardware
+ EQ, mpu401, gameport. A3D and wavetable support are still in development.
+ Development and reverse engineering work is being coordinated at
+ http://savannah.nongnu.org/projects/openvortex/
+ SPDIF output has a copy of the AC97 codec output, unless you use the
+ "spdif" pcm device, which allows raw data passthru.
+ The hardware EQ hardware and SPDIF is only present in the Vortex2 and
+ Advantage.
+
+ Note: Some ALSA mixer applications don't handle the SPDIF sample rate
+ control correctly. If you have problems regarding this, try
+ another ALSA compliant mixer (alsamixer works).
+
+ Module snd-aw2
+ --------------
+
+ Module for Audiowerk2 sound card
+
+ This module supports multiple cards.
+
+ Module snd-azt2320
+ ------------------
+
+ Module for sound cards based on Aztech System AZT2320 ISA chip (PnP only).
+
+ This module supports multiple cards, PnP and autoprobe.
+
+ The power-management is supported.
+
+ Module snd-azt3328
+ ------------------
+
+ Module for sound cards based on Aztech AZF3328 PCI chip.
+
+ joystick - Enable joystick (default off)
+
+ This module supports multiple cards.
+
+ Module snd-bt87x
+ ----------------
+
+ Module for video cards based on Bt87x chips.
+
+ digital_rate - Override the default digital rate (Hz)
+ load_all - Load the driver even if the card model isn't known
+
+ This module supports multiple cards.
+
+ Note: The default index value of this module is -2, i.e. the first
+ slot is excluded.
+
+ Module snd-ca0106
+ -----------------
+
+ Module for Creative Audigy LS and SB Live 24bit
+
+ This module supports multiple cards.
+
+
+ Module snd-cmi8330
+ ------------------
+
+ Module for sound cards based on C-Media CMI8330 ISA chips.
+
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ wssport - port # for CMI8330 chip (WSS)
+ wssirq - IRQ # for CMI8330 chip (WSS)
+ wssdma - first DMA # for CMI8330 chip (WSS)
+ sbport - port # for CMI8330 chip (SB16)
+ sbirq - IRQ # for CMI8330 chip (SB16)
+ sbdma8 - 8bit DMA # for CMI8330 chip (SB16)
+ sbdma16 - 16bit DMA # for CMI8330 chip (SB16)
+
+ This module supports multiple cards and autoprobe.
+
+ The power-management is supported.
+
+ Module snd-cmipci
+ -----------------
+
+ Module for C-Media CMI8338/8738/8768/8770 PCI sound cards.
+
+ mpu_port - port address of MIDI interface (8338 only):
+ 0x300,0x310,0x320,0x330 = legacy port,
+ 0 = disable (default)
+ fm_port - port address of OPL-3 FM synthesizer (8x38 only):
+ 0x388 = legacy port,
+ 1 = integrated PCI port (default on 8738),
+ 0 = disable
+ soft_ac3 - Software-conversion of raw SPDIF packets (model 033 only)
+ (default = 1)
+ joystick_port - Joystick port address (0 = disable, 1 = auto-detect)
+
+ This module supports autoprobe and multiple cards.
+
+ The power-management is supported.
+
+ Module snd-cs4231
+ -----------------
+
+ Module for sound cards based on CS4231 ISA chips.
+
+ port - port # for CS4231 chip
+ mpu_port - port # for MPU-401 UART (optional), -1 = disable
+ irq - IRQ # for CS4231 chip
+ mpu_irq - IRQ # for MPU-401 UART
+ dma1 - first DMA # for CS4231 chip
+ dma2 - second DMA # for CS4231 chip
+
+ This module supports multiple cards. This module does not support autoprobe
+ thus main port must be specified!!! Other ports are optional.
+
+ The power-management is supported.
+
+ Module snd-cs4232
+ -----------------
+
+ Module for sound cards based on CS4232/CS4232A ISA chips.
+
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ port - port # for CS4232 chip (PnP setup - 0x534)
+ cport - control port # for CS4232 chip (PnP setup - 0x120,0x210,0xf00)
+ mpu_port - port # for MPU-401 UART (PnP setup - 0x300), -1 = disable
+ fm_port - FM port # for CS4232 chip (PnP setup - 0x388), -1 = disable
+ irq - IRQ # for CS4232 chip (5,7,9,11,12,15)
+ mpu_irq - IRQ # for MPU-401 UART (9,11,12,15)
+ dma1 - first DMA # for CS4232 chip (0,1,3)
+ dma2 - second DMA # for Yamaha CS4232 chip (0,1,3), -1 = disable
+
+ This module supports multiple cards. This module does not support autoprobe
+ (if ISA PnP is not used) thus main port must be specified!!! Other ports are
+ optional.
+
+ The power-management is supported.
+
+ Module snd-cs4236
+ -----------------
+
+ Module for sound cards based on CS4235/CS4236/CS4236B/CS4237B/
+ CS4238B/CS4239 ISA chips.
+
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ port - port # for CS4236 chip (PnP setup - 0x534)
+ cport - control port # for CS4236 chip (PnP setup - 0x120,0x210,0xf00)
+ mpu_port - port # for MPU-401 UART (PnP setup - 0x300), -1 = disable
+ fm_port - FM port # for CS4236 chip (PnP setup - 0x388), -1 = disable
+ irq - IRQ # for CS4236 chip (5,7,9,11,12,15)
+ mpu_irq - IRQ # for MPU-401 UART (9,11,12,15)
+ dma1 - first DMA # for CS4236 chip (0,1,3)
+ dma2 - second DMA # for CS4236 chip (0,1,3), -1 = disable
+
+ This module supports multiple cards. This module does not support autoprobe
+ (if ISA PnP is not used) thus main port and control port must be
+ specified!!! Other ports are optional.
+
+ The power-management is supported.
+
+ Module snd-cs4281
+ -----------------
+
+ Module for Cirrus Logic CS4281 soundchip.
+
+ dual_codec - Secondary codec ID (0 = disable, default)
+
+ This module supports multiple cards.
+
+ The power-management is supported.
+
+ Module snd-cs46xx
+ -----------------
+
+ Module for PCI sound cards based on CS4610/CS4612/CS4614/CS4615/CS4622/
+ CS4624/CS4630/CS4280 PCI chips.
+
+ external_amp - Force to enable external amplifier.
+ thinkpad - Force to enable Thinkpad's CLKRUN control.
+ mmap_valid - Support OSS mmap mode (default = 0).
+
+ This module supports multiple cards and autoprobe.
+ Usually external amp and CLKRUN controls are detected automatically
+ from PCI sub vendor/device ids. If they don't work, give the options
+ above explicitly.
+
+ The power-management is supported.
+
+ Module snd-cs5530
+ _________________
+
+ Module for Cyrix/NatSemi Geode 5530 chip.
+
+ Module snd-cs5535audio
+ ----------------------
+
+ Module for multifunction CS5535 companion PCI device
+
+ The power-management is supported.
+
+ Module snd-darla20
+ ------------------
+
+ Module for Echoaudio Darla20
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-darla24
+ ------------------
+
+ Module for Echoaudio Darla24
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-dt019x
+ -----------------
+
+ Module for Diamond Technologies DT-019X / Avance Logic ALS-007 (PnP
+ only)
+
+ This module supports multiple cards. This module is enabled only with
+ ISA PnP support.
+
+ The power-management is supported.
+
+ Module snd-dummy
+ ----------------
+
+ Module for the dummy sound card. This "card" doesn't do any output
+ or input, but you may use this module for any application which
+ requires a sound card (like RealPlayer).
+
+ The power-management is supported.
+
+ Module snd-echo3g
+ -----------------
+
+ Module for Echoaudio 3G cards (Gina3G/Layla3G)
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-emu10k1
+ ------------------
+
+ Module for EMU10K1/EMU10k2 based PCI sound cards.
+ * Sound Blaster Live!
+ * Sound Blaster PCI 512
+ * Emu APS (partially supported)
+ * Sound Blaster Audigy
+
+ extin - bitmap of available external inputs for FX8010 (see bellow)
+ extout - bitmap of available external outputs for FX8010 (see bellow)
+ seq_ports - allocated sequencer ports (4 by default)
+ max_synth_voices - limit of voices used for wavetable (64 by default)
+ max_buffer_size - specifies the maximum size of wavetable/pcm buffers
+ given in MB unit. Default value is 128.
+ enable_ir - enable IR
+
+ This module supports multiple cards and autoprobe.
+
+ Input & Output configurations [extin/extout]
+ * Creative Card wo/Digital out [0x0003/0x1f03]
+ * Creative Card w/Digital out [0x0003/0x1f0f]
+ * Creative Card w/Digital CD in [0x000f/0x1f0f]
+ * Creative Card wo/Digital out + LiveDrive [0x3fc3/0x1fc3]
+ * Creative Card w/Digital out + LiveDrive [0x3fc3/0x1fcf]
+ * Creative Card w/Digital CD in + LiveDrive [0x3fcf/0x1fcf]
+ * Creative Card wo/Digital out + Digital I/O 2 [0x0fc3/0x1f0f]
+ * Creative Card w/Digital out + Digital I/O 2 [0x0fc3/0x1f0f]
+ * Creative Card w/Digital CD in + Digital I/O 2 [0x0fcf/0x1f0f]
+ * Creative Card 5.1/w Digital out + LiveDrive [0x3fc3/0x1fff]
+ * Creative Card 5.1 (c) 2003 [0x3fc3/0x7cff]
+ * Creative Card all ins and outs [0x3fff/0x7fff]
+
+ The power-management is supported.
+
+ Module snd-emu10k1x
+ -------------------
+
+ Module for Creative Emu10k1X (SB Live Dell OEM version)
+
+ This module supports multiple cards.
+
+ Module snd-ens1370
+ ------------------
+
+ Module for Ensoniq AudioPCI ES1370 PCI sound cards.
+ * SoundBlaster PCI 64
+ * SoundBlaster PCI 128
+
+ joystick - Enable joystick (default off)
+
+ This module supports multiple cards and autoprobe.
+
+ The power-management is supported.
+
+ Module snd-ens1371
+ ------------------
+
+ Module for Ensoniq AudioPCI ES1371 PCI sound cards.
+ * SoundBlaster PCI 64
+ * SoundBlaster PCI 128
+ * SoundBlaster Vibra PCI
+
+ joystick_port - port # for joystick (0x200,0x208,0x210,0x218),
+ 0 = disable (default), 1 = auto-detect
+
+ This module supports multiple cards and autoprobe.
+
+ The power-management is supported.
+
+ Module snd-es968
+ ----------------
+
+ Module for sound cards based on ESS ES968 chip (PnP only).
+
+ This module supports multiple cards, PnP and autoprobe.
+
+ The power-management is supported.
+
+ Module snd-es1688
+ -----------------
+
+ Module for ESS AudioDrive ES-1688 and ES-688 sound cards.
+
+ port - port # for ES-1688 chip (0x220,0x240,0x260)
+ mpu_port - port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable (default)
+ irq - IRQ # for ES-1688 chip (5,7,9,10)
+ mpu_irq - IRQ # for MPU-401 port (5,7,9,10)
+ dma8 - DMA # for ES-1688 chip (0,1,3)
+
+ This module supports multiple cards and autoprobe (without MPU-401 port).
+
+ Module snd-es18xx
+ -----------------
+
+ Module for ESS AudioDrive ES-18xx sound cards.
+
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ port - port # for ES-18xx chip (0x220,0x240,0x260)
+ mpu_port - port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable (default)
+ fm_port - port # for FM (optional, not used)
+ irq - IRQ # for ES-18xx chip (5,7,9,10)
+ dma1 - first DMA # for ES-18xx chip (0,1,3)
+ dma2 - first DMA # for ES-18xx chip (0,1,3)
+
+ This module supports multiple cards, ISA PnP and autoprobe (without MPU-401
+ port if native ISA PnP routines are not used).
+ When dma2 is equal with dma1, the driver works as half-duplex.
+
+ The power-management is supported.
+
+ Module snd-es1938
+ -----------------
+
+ Module for sound cards based on ESS Solo-1 (ES1938,ES1946) chips.
+
+ This module supports multiple cards and autoprobe.
+
+ The power-management is supported.
+
+ Module snd-es1968
+ -----------------
+
+ Module for sound cards based on ESS Maestro-1/2/2E (ES1968/ES1978) chips.
+
+ total_bufsize - total buffer size in kB (1-4096kB)
+ pcm_substreams_p - playback channels (1-8, default=2)
+ pcm_substreams_c - capture channels (1-8, default=0)
+ clock - clock (0 = auto-detection)
+ use_pm - support the power-management (0 = off, 1 = on,
+ 2 = auto (default))
+ enable_mpu - enable MPU401 (0 = off, 1 = on, 2 = auto (default))
+ joystick - enable joystick (default off)
+
+ This module supports multiple cards and autoprobe.
+
+ The power-management is supported.
+
+ Module snd-fm801
+ ----------------
+
+ Module for ForteMedia FM801 based PCI sound cards.
+
+ tea575x_tuner - Enable TEA575x tuner
+ - 1 = MediaForte 256-PCS
+ - 2 = MediaForte 256-PCPR
+ - 3 = MediaForte 64-PCR
+ - High 16-bits are video (radio) device number + 1
+ - example: 0x10002 (MediaForte 256-PCPR, device 1)
+
+ This module supports multiple cards and autoprobe.
+
+ The power-management is supported.
+
+ Module snd-gina20
+ -----------------
+
+ Module for Echoaudio Gina20
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-gina24
+ -----------------
+
+ Module for Echoaudio Gina24
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-gusclassic
+ ---------------------
+
+ Module for Gravis UltraSound Classic sound card.
+
+ port - port # for GF1 chip (0x220,0x230,0x240,0x250,0x260)
+ irq - IRQ # for GF1 chip (3,5,9,11,12,15)
+ dma1 - DMA # for GF1 chip (1,3,5,6,7)
+ dma2 - DMA # for GF1 chip (1,3,5,6,7,-1=disable)
+ joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V)
+ voices - GF1 voices limit (14-32)
+ pcm_voices - reserved PCM voices
+
+ This module supports multiple cards and autoprobe.
+
+ Module snd-gusextreme
+ ---------------------
+
+ Module for Gravis UltraSound Extreme (Synergy ViperMax) sound card.
+
+ port - port # for ES-1688 chip (0x220,0x230,0x240,0x250,0x260)
+ gf1_port - port # for GF1 chip (0x210,0x220,0x230,0x240,0x250,0x260,0x270)
+ mpu_port - port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable
+ irq - IRQ # for ES-1688 chip (5,7,9,10)
+ gf1_irq - IRQ # for GF1 chip (3,5,9,11,12,15)
+ mpu_irq - IRQ # for MPU-401 port (5,7,9,10)
+ dma8 - DMA # for ES-1688 chip (0,1,3)
+ dma1 - DMA # for GF1 chip (1,3,5,6,7)
+ joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V)
+ voices - GF1 voices limit (14-32)
+ pcm_voices - reserved PCM voices
+
+ This module supports multiple cards and autoprobe (without MPU-401 port).
+
+ Module snd-gusmax
+ -----------------
+
+ Module for Gravis UltraSound MAX sound card.
+
+ port - port # for GF1 chip (0x220,0x230,0x240,0x250,0x260)
+ irq - IRQ # for GF1 chip (3,5,9,11,12,15)
+ dma1 - DMA # for GF1 chip (1,3,5,6,7)
+ dma2 - DMA # for GF1 chip (1,3,5,6,7,-1=disable)
+ joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V)
+ voices - GF1 voices limit (14-32)
+ pcm_voices - reserved PCM voices
+
+ This module supports multiple cards and autoprobe.
+
+ Module snd-hda-intel
+ --------------------
+
+ Module for Intel HD Audio (ICH6, ICH6M, ESB2, ICH7, ICH8, ICH9, ICH10,
+ PCH, SCH),
+ ATI SB450, SB600, R600, RS600, RS690, RS780, RV610, RV620,
+ RV630, RV635, RV670, RV770,
+ VIA VT8251/VT8237A,
+ SIS966, ULI M5461
+
+ [Multiple options for each card instance]
+ model - force the model name
+ position_fix - Fix DMA pointer (0 = auto, 1 = use LPIB, 2 = POSBUF)
+ probe_mask - Bitmask to probe codecs (default = -1, meaning all slots)
+ bdl_pos_adj - Specifies the DMA IRQ timing delay in samples.
+ Passing -1 will make the driver to choose the appropriate
+ value based on the controller chip.
+
+ [Single (global) options]
+ single_cmd - Use single immediate commands to communicate with
+ codecs (for debugging only)
+ enable_msi - Enable Message Signaled Interrupt (MSI) (default = off)
+ power_save - Automatic power-saving timtout (in second, 0 =
+ disable)
+ power_save_controller - Reset HD-audio controller in power-saving mode
+ (default = on)
+
+ This module supports multiple cards and autoprobe.
+
+ Each codec may have a model table for different configurations.
+ If your machine isn't listed there, the default (usually minimal)
+ configuration is set up. You can pass "model=<name>" option to
+ specify a certain model in such a case. There are different
+ models depending on the codec chip.
+
+ 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
+ w810 3-jack
+ z71v 3-jack (HP shared SPDIF)
+ asus 3-jack (ASUS Mobo)
+ asus-w1v ASUS W1V
+ asus-dig ASUS with SPDIF out
+ asus-dig2 ASUS with SPDIF out (using GPIO2)
+ uniwill 3-jack
+ fujitsu Fujitsu Laptops (Pi1536)
+ F1734 2-jack
+ lg LG laptop (m1 express dual)
+ lg-lw LG LW20/LW25 laptop
+ tcl TCL S700
+ clevo Clevo laptops (m520G, m665n)
+ medion Medion Rim 2150
+ test for testing/debugging purpose, almost all controls can be
+ adjusted. Appearing only when compiled with
+ $CONFIG_SND_DEBUG=y
+ auto auto-config reading BIOS (default)
+
+ ALC260
+ hp HP machines
+ hp-3013 HP machines (3013-variant)
+ hp-dc7600 HP DC7600
+ fujitsu Fujitsu S7020
+ acer Acer TravelMate
+ will Will laptops (PB V7900)
+ replacer Replacer 672V
+ basic fixed pin assignment (old default model)
+ test for testing/debugging purpose, almost all controls can
+ adjusted. Appearing only when compiled with
+ $CONFIG_SND_DEBUG=y
+ auto auto-config reading BIOS (default)
+
+ ALC262
+ fujitsu Fujitsu Laptop
+ hp-bpc HP xw4400/6400/8400/9400 laptops
+ hp-bpc-d7000 HP BPC D7000
+ hp-tc-t5735 HP Thin Client T5735
+ hp-rp5700 HP RP5700
+ benq Benq ED8
+ benq-t31 Benq T31
+ hippo Hippo (ATI) with jack detection, Sony UX-90s
+ hippo_1 Hippo (Benq) with jack detection
+ sony-assamd Sony ASSAMD
+ toshiba-s06 Toshiba S06
+ toshiba-rx1 Toshiba RX1
+ ultra Samsung Q1 Ultra Vista model
+ lenovo-3000 Lenovo 3000 y410
+ nec NEC Versa S9100
+ basic fixed pin assignment w/o SPDIF
+ auto auto-config reading BIOS (default)
+
+ ALC267/268
+ quanta-il1 Quanta IL1 mini-notebook
+ 3stack 3-stack model
+ toshiba Toshiba A205
+ acer Acer laptops
+ acer-aspire Acer Aspire One
+ dell Dell OEM laptops (Vostro 1200)
+ zepto Zepto laptops
+ test for testing/debugging purpose, almost all controls can
+ adjusted. Appearing only when compiled with
+ $CONFIG_SND_DEBUG=y
+ auto auto-config reading BIOS (default)
+
+ ALC269
+ basic Basic preset
+ quanta Quanta FL1
+ eeepc-p703 ASUS Eeepc P703 P900A
+ eeepc-p901 ASUS Eeepc P901 S101
+
+ ALC662/663
+ 3stack-dig 3-stack (2-channel) with SPDIF
+ 3stack-6ch 3-stack (6-channel)
+ 3stack-6ch-dig 3-stack (6-channel) with SPDIF
+ 6stack-dig 6-stack with SPDIF
+ lenovo-101e Lenovo laptop
+ eeepc-p701 ASUS Eeepc P701
+ eeepc-ep20 ASUS Eeepc EP20
+ ecs ECS/Foxconn mobo
+ m51va ASUS M51VA
+ g71v ASUS G71V
+ h13 ASUS H13
+ g50v ASUS G50V
+ asus-mode1 ASUS
+ asus-mode2 ASUS
+ asus-mode3 ASUS
+ asus-mode4 ASUS
+ asus-mode5 ASUS
+ asus-mode6 ASUS
+ auto auto-config reading BIOS (default)
+
+ ALC882/885
+ 3stack-dig 3-jack with SPDIF I/O
+ 6stack-dig 6-jack digital with SPDIF I/O
+ arima Arima W820Di1
+ targa Targa T8, MSI-1049 T8
+ asus-a7j ASUS A7J
+ asus-a7m ASUS A7M
+ macpro MacPro support
+ mbp3 Macbook Pro rev3
+ imac24 iMac 24'' with jack detection
+ w2jc ASUS W2JC
+ auto auto-config reading BIOS (default)
+
+ ALC883/888
+ 3stack-dig 3-jack with SPDIF I/O
+ 6stack-dig 6-jack digital with SPDIF I/O
+ 3stack-6ch 3-jack 6-channel
+ 3stack-6ch-dig 3-jack 6-channel with SPDIF I/O
+ 6stack-dig-demo 6-jack digital for Intel demo board
+ acer Acer laptops (Travelmate 3012WTMi, Aspire 5600, etc)
+ acer-aspire Acer Aspire 9810
+ medion Medion Laptops
+ medion-md2 Medion MD2
+ targa-dig Targa/MSI
+ targa-2ch-dig Targs/MSI with 2-channel
+ laptop-eapd 3-jack with SPDIF I/O and EAPD (Clevo M540JE, M550JE)
+ lenovo-101e Lenovo 101E
+ lenovo-nb0763 Lenovo NB0763
+ lenovo-ms7195-dig Lenovo MS7195
+ lenovo-sky Lenovo Sky
+ haier-w66 Haier W66
+ 3stack-hp HP machines with 3stack (Lucknow, Samba boards)
+ 6stack-dell Dell machines with 6stack (Inspiron 530)
+ mitac Mitac 8252D
+ clevo-m720 Clevo M720 laptop series
+ fujitsu-pi2515 Fujitsu AMILO Pi2515
+ 3stack-6ch-intel Intel DG33* boards
+ auto auto-config reading BIOS (default)
+
+ ALC861/660
+ 3stack 3-jack
+ 3stack-dig 3-jack with SPDIF I/O
+ 6stack-dig 6-jack with SPDIF I/O
+ 3stack-660 3-jack (for ALC660)
+ uniwill-m31 Uniwill M31 laptop
+ toshiba Toshiba laptop support
+ asus Asus laptop support
+ asus-laptop ASUS F2/F3 laptops
+ auto auto-config reading BIOS (default)
+
+ ALC861VD/660VD
+ 3stack 3-jack
+ 3stack-dig 3-jack with SPDIF OUT
+ 6stack-dig 6-jack with SPDIF OUT
+ 3stack-660 3-jack (for ALC660VD)
+ 3stack-660-digout 3-jack with SPDIF OUT (for ALC660VD)
+ lenovo Lenovo 3000 C200
+ dallas Dallas laptops
+ hp HP TX1000
+ auto auto-config reading BIOS (default)
+
+ 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 (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
+
+ 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 Dell T3400
+
+ AD1986A
+ 6stack 6-jack, separate surrounds (default)
+ 3stack 3-stack, shared surrounds
+ laptop 2-channel only (FSC V2060, Samsung M50)
+ laptop-eapd 2-channel with EAPD (ASUS A6J)
+ laptop-automute 2-channel with EAPD and HP-automute (Lenovo N100)
+ ultra 2-channel with EAPD (Samsung Ultra tablet PC)
+ samsung 2-channel with EAPD (Samsung R65)
+
+ 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
+ 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
+
+ STAC9200
+ ref Reference board
+ 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 Gateway laptops with EAPD control
+ panasonic Panasonic CF-74
+
+ STAC9205/9254
+ ref Reference board
+ dell-m42 Dell (unknown)
+ dell-m43 Dell Precision
+ dell-m44 Dell Inspiron
+
+ 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)
+ dell-d81 Dell (unknown)
+ dell-d82 Dell (unknown)
+ dell-m81 Dell (unknown)
+ dell-m82 Dell XPS M1210
+
+ STAC9202/9250/9251
+ ref Reference board, base config
+ m2-2 Some Gateway MX series laptops
+ m6 Some Gateway NX series laptops
+ pa6 Gateway NX860 series
+
+ STAC9227/9228/9229/927x
+ ref Reference board
+ ref-no-jd Reference board without HP/Mic jack detection
+ 3stack D965 3stack
+ 5stack D965 5stack + SPDIF
+ dell-3stack Dell Dimension E520
+ dell-bios Fixes with Dell BIOS setup
+
+ STAC92HD71B*
+ ref Reference board
+ dell-m4-1 Dell desktops
+ dell-m4-2 Dell desktops
+ dell-m4-3 Dell desktops
+
+ STAC92HD73*
+ ref Reference board
+ no-jd BIOS setup but without jack-detection
+ 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
+
+ STAC9872
+ vaio Setup for VAIO FE550G/SZ110
+ vaio-ar Setup for VAIO AR
+
+ The model name "genric" is treated as a special case. When this
+ model is given, the driver uses the generic codec parser without
+ "codec-patch". It's sometimes good for testing and debugging.
+
+ If the default configuration doesn't work and one of the above
+ matches with your device, report it together with the PCI
+ subsystem ID (output of "lspci -nv") to ALSA BTS or alsa-devel
+ ML (see the section "Links and Addresses").
+
+ power_save and power_save_controller options are for power-saving
+ mode. See powersave.txt for details.
+
+ Note 2: If you get click noises on output, try the module option
+ position_fix=1 or 2. position_fix=1 will use the SD_LPIB
+ register value without FIFO size correction as the current
+ DMA pointer. position_fix=2 will make the driver to use
+ the position buffer instead of reading SD_LPIB register.
+ (Usually SD_LPIB register is more accurate than the
+ position buffer.)
+
+ NB: If you get many "azx_get_response timeout" messages at
+ loading, it's likely a problem of interrupts (e.g. ACPI irq
+ routing). Try to boot with options like "pci=noacpi". Also, you
+ can try "single_cmd=1" module option. This will switch the
+ communication method between HDA controller and codecs to the
+ single immediate commands instead of CORB/RIRB. Basically, the
+ single command mode is provided only for BIOS, and you won't get
+ unsolicited events, too. But, at least, this works independently
+ from the irq. Remember this is a last resort, and should be
+ avoided as much as possible...
+
+ MORE NOTES ON "azx_get_response timeout" PROBLEMS:
+ On some hardwares, you may need to add a proper probe_mask option
+ to avoid the "azx_get_response timeout" problem above, instead.
+ This occurs when the access to non-existing or non-working codec slot
+ (likely a modem one) causes a stall of the communication via HD-audio
+ bus. You can see which codec slots are probed by enabling
+ CONFIG_SND_DEBUG_VERBOSE, or simply from the file name of the codec
+ proc files. Then limit the slots to probe by probe_mask option.
+ For example, probe_mask=1 means to probe only the first slot, and
+ probe_mask=4 means only the third slot.
+
+ The power-management is supported.
+
+ Module snd-hdsp
+ ---------------
+
+ Module for RME Hammerfall DSP audio interface(s)
+
+ This module supports multiple cards.
+
+ Note: The firmware data can be automatically loaded via hotplug
+ when CONFIG_FW_LOADER is set. Otherwise, you need to load
+ the firmware via hdsploader utility included in alsa-tools
+ package.
+ The firmware data is found in alsa-firmware package.
+
+ Note: snd-page-alloc module does the job which snd-hammerfall-mem
+ module did formerly. It will allocate the buffers in advance
+ when any HDSP cards are found. To make the buffer
+ allocation sure, load snd-page-alloc module in the early
+ stage of boot sequence. See "Early Buffer Allocation"
+ section.
+
+ Module snd-hdspm
+ ----------------
+
+ Module for RME HDSP MADI board.
+
+ precise_ptr - Enable precise pointer, or disable.
+ line_outs_monitor - Send playback streams to analog outs by default.
+ enable_monitor - Enable Analog Out on Channel 63/64 by default.
+
+ See hdspm.txt for details.
+
+ Module snd-hifier
+ -----------------
+
+ Module for the MediaTek/TempoTec HiFier Fantasia sound card.
+
+ This module supports autoprobe and multiple cards.
+
+ Module snd-ice1712
+ ------------------
+
+ Module for Envy24 (ICE1712) based PCI sound cards.
+ * MidiMan M Audio Delta 1010
+ * MidiMan M Audio Delta 1010LT
+ * MidiMan M Audio Delta DiO 2496
+ * MidiMan M Audio Delta 66
+ * MidiMan M Audio Delta 44
+ * MidiMan M Audio Delta 410
+ * MidiMan M Audio Audiophile 2496
+ * TerraTec EWS 88MT
+ * TerraTec EWS 88D
+ * TerraTec EWX 24/96
+ * TerraTec DMX 6Fire
+ * TerraTec Phase 88
+ * Hoontech SoundTrack DSP 24
+ * Hoontech SoundTrack DSP 24 Value
+ * Hoontech SoundTrack DSP 24 Media 7.1
+ * Event Electronics, EZ8
+ * Digigram VX442
+ * Lionstracs, Mediastaton
+ * Terrasoniq TS 88
+
+ model - Use the given board model, one of the following:
+ delta1010, dio2496, delta66, delta44, audiophile, delta410,
+ delta1010lt, vx442, ewx2496, ews88mt, ews88mt_new, ews88d,
+ dmx6fire, dsp24, dsp24_value, dsp24_71, ez8,
+ phase88, mediastation
+ omni - Omni I/O support for MidiMan M-Audio Delta44/66
+ cs8427_timeout - reset timeout for the CS8427 chip (S/PDIF transceiver)
+ in msec resolution, default value is 500 (0.5 sec)
+
+ This module supports multiple cards and autoprobe. Note: The consumer part
+ is not used with all Envy24 based cards (for example in the MidiMan Delta
+ serie).
+
+ Note: The supported board is detected by reading EEPROM or PCI
+ SSID (if EEPROM isn't available). You can override the
+ model by passing "model" module option in case that the
+ driver isn't configured properly or you want to try another
+ type for testing.
+
+ Module snd-ice1724
+ ------------------
+
+ Module for Envy24HT (VT/ICE1724), Envy24PT (VT1720) based PCI sound cards.
+ * MidiMan M Audio Revolution 5.1
+ * MidiMan M Audio Revolution 7.1
+ * MidiMan M Audio Audiophile 192
+ * AMP Ltd AUDIO2000
+ * TerraTec Aureon 5.1 Sky
+ * TerraTec Aureon 7.1 Space
+ * TerraTec Aureon 7.1 Universe
+ * TerraTec Phase 22
+ * TerraTec Phase 28
+ * AudioTrak Prodigy 7.1
+ * AudioTrak Prodigy 7.1 LT
+ * AudioTrak Prodigy 7.1 XT
+ * AudioTrak Prodigy 7.1 HIFI
+ * AudioTrak Prodigy 7.1 HD2
+ * AudioTrak Prodigy 192
+ * Pontis MS300
+ * Albatron K8X800 Pro II
+ * Chaintech ZNF3-150
+ * Chaintech ZNF3-250
+ * Chaintech 9CJS
+ * Chaintech AV-710
+ * Shuttle SN25P
+ * Onkyo SE-90PCI
+ * Onkyo SE-200PCI
+ * ESI Juli@
+ * Hercules Fortissimo IV
+ * EGO-SYS WaveTerminal 192M
+
+ model - Use the given board model, one of the following:
+ revo51, revo71, amp2000, prodigy71, prodigy71lt,
+ prodigy71xt, prodigy71hifi, prodigyhd2, prodigy192,
+ juli, aureon51, aureon71, universe, ap192, k8x800,
+ phase22, phase28, ms300, av710, se200pci, se90pci,
+ fortissimo4, sn25p, WT192M
+
+ This module supports multiple cards and autoprobe.
+
+ Note: The supported board is detected by reading EEPROM or PCI
+ SSID (if EEPROM isn't available). You can override the
+ model by passing "model" module option in case that the
+ driver isn't configured properly or you want to try another
+ type for testing.
+
+ Module snd-indigo
+ -----------------
+
+ Module for Echoaudio Indigo
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-indigodj
+ -------------------
+
+ Module for Echoaudio Indigo DJ
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-indigoio
+ -------------------
+
+ Module for Echoaudio Indigo IO
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-intel8x0
+ -------------------
+
+ Module for AC'97 motherboards from Intel and compatibles.
+ * Intel i810/810E, i815, i820, i830, i84x, MX440
+ ICH5, ICH6, ICH7, 6300ESB, ESB2
+ * SiS 7012 (SiS 735)
+ * NVidia NForce, NForce2, NForce3, MCP04, CK804
+ CK8, CK8S, MCP501
+ * AMD AMD768, AMD8111
+ * ALi m5455
+
+ ac97_clock - AC'97 codec clock base (0 = auto-detect)
+ ac97_quirk - AC'97 workaround for strange hardware
+ See "AC97 Quirk Option" section below.
+ buggy_irq - Enable workaround for buggy interrupts on some
+ motherboards (default yes on nForce chips,
+ otherwise off)
+ buggy_semaphore - Enable workaround for hardwares with buggy
+ semaphores (e.g. on some ASUS laptops)
+ (default off)
+ spdif_aclink - Use S/PDIF over AC-link instead of direct connection
+ from the controller chip
+ (0 = off, 1 = on, -1 = default)
+
+ This module supports one chip and autoprobe.
+
+ Note: the latest driver supports auto-detection of chip clock.
+ if you still encounter too fast playback, specify the clock
+ explicitly via the module option "ac97_clock=41194".
+
+ Joystick/MIDI ports are not supported by this driver. If your
+ motherboard has these devices, use the ns558 or snd-mpu401
+ modules, respectively.
+
+ The power-management is supported.
+
+ Module snd-intel8x0m
+ --------------------
+
+ Module for Intel ICH (i8x0) chipset MC97 modems.
+ * Intel i810/810E, i815, i820, i830, i84x, MX440
+ ICH5, ICH6, ICH7
+ * SiS 7013 (SiS 735)
+ * NVidia NForce, NForce2, NForce2s, NForce3
+ * AMD AMD8111
+ * ALi m5455
+
+ ac97_clock - AC'97 codec clock base (0 = auto-detect)
+
+ This module supports one card and autoprobe.
+
+ Note: The default index value of this module is -2, i.e. the first
+ slot is excluded.
+
+ The power-management is supported.
+
+ Module snd-interwave
+ --------------------
+
+ Module for Gravis UltraSound PnP, Dynasonic 3-D/Pro, STB Sound Rage 32
+ and other sound cards based on AMD InterWave (tm) chip.
+
+ joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V)
+ midi - 1 = MIDI UART enable, 0 = MIDI UART disable (default)
+ pcm_voices - reserved PCM voices for the synthesizer (default 2)
+ effect - 1 = InterWave effects enable (default 0);
+ requires 8 voices
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260)
+ irq - IRQ # for InterWave chip (3,5,9,11,12,15)
+ dma1 - DMA # for InterWave chip (0,1,3,5,6,7)
+ dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable)
+
+ This module supports multiple cards, autoprobe and ISA PnP.
+
+ Module snd-interwave-stb
+ ------------------------
+
+ Module for UltraSound 32-Pro (sound card from STB used by Compaq)
+ and other sound cards based on AMD InterWave (tm) chip with TEA6330T
+ circuit for extended control of bass, treble and master volume.
+
+ joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V)
+ midi - 1 = MIDI UART enable, 0 = MIDI UART disable (default)
+ pcm_voices - reserved PCM voices for the synthesizer (default 2)
+ effect - 1 = InterWave effects enable (default 0);
+ requires 8 voices
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260)
+ port_tc - tone control (i2c bus) port # for TEA6330T chip (0x350,0x360,0x370,0x380)
+ irq - IRQ # for InterWave chip (3,5,9,11,12,15)
+ dma1 - DMA # for InterWave chip (0,1,3,5,6,7)
+ dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable)
+
+ This module supports multiple cards, autoprobe and ISA PnP.
+
+ Module snd-korg1212
+ -------------------
+
+ Module for Korg 1212 IO PCI card
+
+ This module supports multiple cards.
+
+ Module snd-layla20
+ ------------------
+
+ Module for Echoaudio Layla20
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-layla24
+ ------------------
+
+ Module for Echoaudio Layla24
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-maestro3
+ -------------------
+
+ Module for Allegro/Maestro3 chips
+
+ external_amp - enable external amp (enabled by default)
+ amp_gpio - GPIO pin number for external amp (0-15) or
+ -1 for default pin (8 for allegro, 1 for
+ others)
+
+ This module supports autoprobe and multiple chips.
+
+ Note: the binding of amplifier is dependent on hardware.
+ If there is no sound even though all channels are unmuted, try to
+ specify other gpio connection via amp_gpio option.
+ For example, a Panasonic notebook might need "amp_gpio=0x0d"
+ option.
+
+ The power-management is supported.
+
+ Module snd-mia
+ ---------------
+
+ Module for Echoaudio Mia
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-miro
+ ---------------
+
+ Module for Miro soundcards: miroSOUND PCM 1 pro,
+ miroSOUND PCM 12,
+ miroSOUND PCM 20 Radio.
+
+ port - Port # (0x530,0x604,0xe80,0xf40)
+ irq - IRQ # (5,7,9,10,11)
+ dma1 - 1st dma # (0,1,3)
+ dma2 - 2nd dma # (0,1)
+ mpu_port - MPU-401 port # (0x300,0x310,0x320,0x330)
+ mpu_irq - MPU-401 irq # (5,7,9,10)
+ fm_port - FM Port # (0x388)
+ wss - enable WSS mode
+ ide - enable onboard ide support
+
+ Module snd-mixart
+ -----------------
+
+ Module for Digigram miXart8 sound cards.
+
+ This module supports multiple cards.
+ Note: One miXart8 board will be represented as 4 alsa cards.
+ See MIXART.txt for details.
+
+ When the driver is compiled as a module and the hotplug firmware
+ is supported, the firmware data is loaded via hotplug automatically.
+ Install the necessary firmware files in alsa-firmware package.
+ When no hotplug fw loader is available, you need to load the
+ firmware via mixartloader utility in alsa-tools package.
+
+ Module snd-mona
+ ---------------
+
+ Module for Echoaudio Mona
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+
+ Module snd-mpu401
+ -----------------
+
+ Module for MPU-401 UART devices.
+
+ port - port number or -1 (disable)
+ irq - IRQ number or -1 (disable)
+ pnp - PnP detection - 0 = disable, 1 = enable (default)
+
+ This module supports multiple devices and PnP.
+
+ Module snd-mtpav
+ ----------------
+
+ Module for MOTU MidiTimePiece AV multiport MIDI (on the parallel
+ port).
+
+ port - I/O port # for MTPAV (0x378,0x278, default=0x378)
+ irq - IRQ # for MTPAV (7,5, default=7)
+ hwports - number of supported hardware ports, default=8.
+
+ Module supports only 1 card. This module has no enable option.
+
+ Module snd-mts64
+ ----------------
+
+ Module for Ego Systems (ESI) Miditerminal 4140
+
+ This module supports multiple devices.
+ Requires parport (CONFIG_PARPORT).
+
+ Module snd-nm256
+ ----------------
+
+ Module for NeoMagic NM256AV/ZX chips
+
+ playback_bufsize - max playback frame size in kB (4-128kB)
+ capture_bufsize - max capture frame size in kB (4-128kB)
+ force_ac97 - 0 or 1 (disabled by default)
+ buffer_top - specify buffer top address
+ use_cache - 0 or 1 (disabled by default)
+ vaio_hack - alias buffer_top=0x25a800
+ reset_workaround - enable AC97 RESET workaround for some laptops
+ reset_workaround2 - enable extended AC97 RESET workaround for some
+ other laptops
+
+ This module supports one chip and autoprobe.
+
+ The power-management is supported.
+
+ Note: on some notebooks the buffer address cannot be detected
+ automatically, or causes hang-up during initialization.
+ In such a case, specify the buffer top address explicitly via
+ the buffer_top option.
+ For example,
+ Sony F250: buffer_top=0x25a800
+ Sony F270: buffer_top=0x272800
+ The driver supports only ac97 codec. It's possible to force
+ to initialize/use ac97 although it's not detected. In such a
+ case, use force_ac97=1 option - but *NO* guarantee whether it
+ works!
+
+ Note: The NM256 chip can be linked internally with non-AC97
+ codecs. This driver supports only the AC97 codec, and won't work
+ with machines with other (most likely CS423x or OPL3SAx) chips,
+ even though the device is detected in lspci. In such a case, try
+ other drivers, e.g. snd-cs4232 or snd-opl3sa2. Some has ISA-PnP
+ but some doesn't have ISA PnP. You'll need to specify isapnp=0
+ and proper hardware parameters in the case without ISA PnP.
+
+ Note: some laptops need a workaround for AC97 RESET. For the
+ known hardware like Dell Latitude LS and Sony PCG-F305, this
+ workaround is enabled automatically. For other laptops with a
+ hard freeze, you can try reset_workaround=1 option.
+
+ Note: Dell Latitude CSx laptops have another problem regarding
+ AC97 RESET. On these laptops, reset_workaround2 option is
+ turned on as default. This option is worth to try if the
+ previous reset_workaround option doesn't help.
+
+ Note: This driver is really crappy. It's a porting from the
+ OSS driver, which is a result of black-magic reverse engineering.
+ The detection of codec will fail if the driver is loaded *after*
+ X-server as described above. You might be able to force to load
+ the module, but it may result in hang-up. Hence, make sure that
+ you load this module *before* X if you encounter this kind of
+ problem.
+
+ Module snd-opl3sa2
+ ------------------
+
+ Module for Yamaha OPL3-SA2/SA3 sound cards.
+
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ port - control port # for OPL3-SA chip (0x370)
+ sb_port - SB port # for OPL3-SA chip (0x220,0x240)
+ wss_port - WSS port # for OPL3-SA chip (0x530,0xe80,0xf40,0x604)
+ midi_port - port # for MPU-401 UART (0x300,0x330), -1 = disable
+ fm_port - FM port # for OPL3-SA chip (0x388), -1 = disable
+ irq - IRQ # for OPL3-SA chip (5,7,9,10)
+ dma1 - first DMA # for Yamaha OPL3-SA chip (0,1,3)
+ dma2 - second DMA # for Yamaha OPL3-SA chip (0,1,3), -1 = disable
+
+ This module supports multiple cards and ISA PnP. It does not support
+ autoprobe (if ISA PnP is not used) thus all ports must be specified!!!
+
+ The power-management is supported.
+
+ Module snd-opti92x-ad1848
+ -------------------------
+
+ Module for sound cards based on OPTi 82c92x and Analog Devices AD1848 chips.
+ Module works with OAK Mozart cards as well.
+
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ port - port # for WSS chip (0x530,0xe80,0xf40,0x604)
+ mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330)
+ fm_port - port # for OPL3 device (0x388)
+ irq - IRQ # for WSS chip (5,7,9,10,11)
+ mpu_irq - IRQ # for MPU-401 UART (5,7,9,10)
+ dma1 - first DMA # for WSS chip (0,1,3)
+
+ This module supports only one card, autoprobe and PnP.
+
+ Module snd-opti92x-cs4231
+ -------------------------
+
+ Module for sound cards based on OPTi 82c92x and Crystal CS4231 chips.
+
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ port - port # for WSS chip (0x530,0xe80,0xf40,0x604)
+ mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330)
+ fm_port - port # for OPL3 device (0x388)
+ irq - IRQ # for WSS chip (5,7,9,10,11)
+ mpu_irq - IRQ # for MPU-401 UART (5,7,9,10)
+ dma1 - first DMA # for WSS chip (0,1,3)
+ dma2 - second DMA # for WSS chip (0,1,3)
+
+ This module supports only one card, autoprobe and PnP.
+
+ Module snd-opti93x
+ ------------------
+
+ Module for sound cards based on OPTi 82c93x chips.
+
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ port - port # for WSS chip (0x530,0xe80,0xf40,0x604)
+ mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330)
+ fm_port - port # for OPL3 device (0x388)
+ irq - IRQ # for WSS chip (5,7,9,10,11)
+ mpu_irq - IRQ # for MPU-401 UART (5,7,9,10)
+ dma1 - first DMA # for WSS chip (0,1,3)
+ dma2 - second DMA # for WSS chip (0,1,3)
+
+ This module supports only one card, autoprobe and PnP.
+
+ Module snd-oxygen
+ -----------------
+
+ Module for sound cards based on the C-Media CMI8788 chip:
+ * Asound A-8788
+ * AuzenTech X-Meridian
+ * Bgears b-Enspirer
+ * Club3D Theatron DTS
+ * HT-Omega Claro
+ * Razer Barracuda AC-1
+ * Sondigo Inferno
+
+ This module supports autoprobe and multiple cards.
+
+ Module snd-pcsp
+ -----------------
+
+ Module for internal PC-Speaker.
+
+ nforce_wa - enable NForce chipset workaround. Expect bad sound.
+
+ This module supports system beeps, some kind of PCM playback and
+ even a few mixer controls.
+
+ Module snd-pcxhr
+ ----------------
+
+ Module for Digigram PCXHR boards
+
+ This module supports multiple cards.
+
+ Module snd-portman2x4
+ ---------------------
+
+ Module for Midiman Portman 2x4 parallel port MIDI interface
+
+ This module supports multiple cards.
+
+ Module snd-powermac (on ppc only)
+ ---------------------------------
+
+ Module for PowerMac, iMac and iBook on-board soundchips
+
+ enable_beep - enable beep using PCM (enabled as default)
+
+ Module supports autoprobe a chip.
+
+ Note: the driver may have problems regarding endianess.
+
+ The power-management is supported.
+
+ Module snd-pxa2xx-ac97 (on arm only)
+ ------------------------------------
+
+ Module for AC97 driver for the Intel PXA2xx chip
+
+ For ARM architecture only.
+
+ The power-management is supported.
+
+ Module snd-riptide
+ ------------------
+
+ Module for Conexant Riptide chip
+
+ joystick_port - Joystick port # (default: 0x200)
+ mpu_port - MPU401 port # (default: 0x330)
+ opl3_port - OPL3 port # (default: 0x388)
+
+ This module supports multiple cards.
+ The driver requires the firmware loader support on kernel.
+ You need to install the firmware file "riptide.hex" to the standard
+ firmware path (e.g. /lib/firmware).
+
+ Module snd-rme32
+ ----------------
+
+ Module for RME Digi32, Digi32 Pro and Digi32/8 (Sek'd Prodif32,
+ Prodif96 and Prodif Gold) sound cards.
+
+ This module supports multiple cards.
+
+ Module snd-rme96
+ ----------------
+
+ Module for RME Digi96, Digi96/8 and Digi96/8 PRO/PAD/PST sound cards.
+
+ This module supports multiple cards.
+
+ Module snd-rme9652
+ ------------------
+
+ Module for RME Digi9652 (Hammerfall, Hammerfall-Light) sound cards.
+
+ precise_ptr - Enable precise pointer (doesn't work reliably).
+ (default = 0)
+
+ This module supports multiple cards.
+
+ Note: snd-page-alloc module does the job which snd-hammerfall-mem
+ module did formerly. It will allocate the buffers in advance
+ when any RME9652 cards are found. To make the buffer
+ allocation sure, load snd-page-alloc module in the early
+ stage of boot sequence. See "Early Buffer Allocation"
+ section.
+
+ Module snd-sa11xx-uda1341 (on arm only)
+ ---------------------------------------
+
+ Module for Philips UDA1341TS on Compaq iPAQ H3600 sound card.
+
+ Module supports only one card.
+ Module has no enable and index options.
+
+ The power-management is supported.
+
+ Module snd-sb8
+ --------------
+
+ Module for 8-bit SoundBlaster cards: SoundBlaster 1.0,
+ SoundBlaster 2.0,
+ SoundBlaster Pro
+
+ port - port # for SB DSP chip (0x220,0x240,0x260)
+ irq - IRQ # for SB DSP chip (5,7,9,10)
+ dma8 - DMA # for SB DSP chip (1,3)
+
+ This module supports multiple cards and autoprobe.
+
+ The power-management is supported.
+
+ Module snd-sb16 and snd-sbawe
+ -----------------------------
+
+ Module for 16-bit SoundBlaster cards: SoundBlaster 16 (PnP),
+ SoundBlaster AWE 32 (PnP),
+ SoundBlaster AWE 64 PnP
+
+ mic_agc - Mic Auto-Gain-Control - 0 = disable, 1 = enable (default)
+ csp - ASP/CSP chip support - 0 = disable (default), 1 = enable
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ port - port # for SB DSP 4.x chip (0x220,0x240,0x260)
+ mpu_port - port # for MPU-401 UART (0x300,0x330), -1 = disable
+ awe_port - base port # for EMU8000 synthesizer (0x620,0x640,0x660)
+ (snd-sbawe module only)
+ irq - IRQ # for SB DSP 4.x chip (5,7,9,10)
+ dma8 - 8-bit DMA # for SB DSP 4.x chip (0,1,3)
+ dma16 - 16-bit DMA # for SB DSP 4.x chip (5,6,7)
+
+ This module supports multiple cards, autoprobe and ISA PnP.
+
+ Note: To use Vibra16X cards in 16-bit half duplex mode, you must
+ disable 16bit DMA with dma16 = -1 module parameter.
+ Also, all Sound Blaster 16 type cards can operate in 16-bit
+ half duplex mode through 8-bit DMA channel by disabling their
+ 16-bit DMA channel.
+
+ The power-management is supported.
+
+ Module snd-sc6000
+ -----------------
+
+ Module for Gallant SC-6000 soundcard.
+
+ port - Port # (0x220 or 0x240)
+ mss_port - MSS Port # (0x530 or 0xe80)
+ irq - IRQ # (5,7,9,10,11)
+ mpu_irq - MPU-401 IRQ # (5,7,9,10) ,0 - no MPU-401 irq
+ dma - DMA # (1,3,0)
+
+ This module supports multiple cards.
+
+ This card is also known as Audio Excel DSP 16 or Zoltrix AV302.
+
+ Module snd-sgalaxy
+ ------------------
+
+ Module for Aztech Sound Galaxy sound card.
+
+ sbport - Port # for SB16 interface (0x220,0x240)
+ wssport - Port # for WSS interface (0x530,0xe80,0xf40,0x604)
+ irq - IRQ # (7,9,10,11)
+ dma1 - DMA #
+
+ This module supports multiple cards.
+
+ The power-management is supported.
+
+ Module snd-sscape
+ -----------------
+
+ Module for ENSONIQ SoundScape PnP cards.
+
+ port - Port # (PnP setup)
+ wss_port - WSS Port # (PnP setup)
+ irq - IRQ # (PnP setup)
+ mpu_irq - MPU-401 IRQ # (PnP setup)
+ dma - DMA # (PnP setup)
+ dma2 - 2nd DMA # (PnP setup, -1 to disable)
+
+ This module supports multiple cards. ISA PnP must be enabled.
+ You need sscape_ctl tool in alsa-tools package for loading
+ the microcode.
+
+ Module snd-sun-amd7930 (on sparc only)
+ --------------------------------------
+
+ Module for AMD7930 sound chips found on Sparcs.
+
+ This module supports multiple cards.
+
+ Module snd-sun-cs4231 (on sparc only)
+ -------------------------------------
+
+ Module for CS4231 sound chips found on Sparcs.
+
+ This module supports multiple cards.
+
+ Module snd-sun-dbri (on sparc only)
+ -----------------------------------
+
+ Module for DBRI sound chips found on Sparcs.
+
+ This module supports multiple cards.
+
+ Module snd-wavefront
+ --------------------
+
+ Module for Turtle Beach Maui, Tropez and Tropez+ sound cards.
+
+ use_cs4232_midi - Use CS4232 MPU-401 interface
+ (inaccessibly located inside your computer)
+ isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+ with isapnp=0, the following options are available:
+
+ cs4232_pcm_port - Port # for CS4232 PCM interface.
+ cs4232_pcm_irq - IRQ # for CS4232 PCM interface (5,7,9,11,12,15).
+ cs4232_mpu_port - Port # for CS4232 MPU-401 interface.
+ cs4232_mpu_irq - IRQ # for CS4232 MPU-401 interface (9,11,12,15).
+ ics2115_port - Port # for ICS2115
+ ics2115_irq - IRQ # for ICS2115
+ fm_port - FM OPL-3 Port #
+ dma1 - DMA1 # for CS4232 PCM interface.
+ dma2 - DMA2 # for CS4232 PCM interface.
+
+ The below are options for wavefront_synth features:
+ wf_raw - Assume that we need to boot the OS (default:no)
+ If yes, then during driver loading, the state of the board is
+ ignored, and we reset the board and load the firmware anyway.
+ fx_raw - Assume that the FX process needs help (default:yes)
+ If false, we'll leave the FX processor in whatever state it is
+ when the driver is loaded. The default is to download the
+ microprogram and associated coefficients to set it up for
+ "default" operation, whatever that means.
+ debug_default - Debug parameters for card initialization
+ wait_usecs - How long to wait without sleeping, usecs
+ (default:150)
+ This magic number seems to give pretty optimal throughput
+ based on my limited experimentation.
+ If you want to play around with it and find a better value, be
+ my guest. Remember, the idea is to get a number that causes us
+ to just busy wait for as many WaveFront commands as possible,
+ without coming up with a number so large that we hog the whole
+ CPU.
+ Specifically, with this number, out of about 134,000 status
+ waits, only about 250 result in a sleep.
+ sleep_interval - How long to sleep when waiting for reply
+ (default: 100)
+ sleep_tries - How many times to try sleeping during a wait
+ (default: 50)
+ ospath - Pathname to processed ICS2115 OS firmware
+ (default:wavefront.os)
+ The path name of the ISC2115 OS firmware. In the recent
+ version, it's handled via firmware loader framework, so it
+ must be installed in the proper path, typically,
+ /lib/firmware.
+ reset_time - How long to wait for a reset to take effect
+ (default:2)
+ ramcheck_time - How many seconds to wait for the RAM test
+ (default:20)
+ osrun_time - How many seconds to wait for the ICS2115 OS
+ (default:10)
+
+ This module supports multiple cards and ISA PnP.
+
+ Note: the firmware file "wavefront.os" was located in the earlier
+ version in /etc. Now it's loaded via firmware loader, and
+ must be in the proper firmware path, such as /lib/firmware.
+ Copy (or symlink) the file appropriately if you get an error
+ regarding firmware downloading after upgrading the kernel.
+
+ Module snd-sonicvibes
+ ---------------------
+
+ Module for S3 SonicVibes PCI sound cards.
+ * PINE Schubert 32 PCI
+
+ reverb - Reverb Enable - 1 = enable, 0 = disable (default)
+ - SoundCard must have onboard SRAM for this.
+ mge - Mic Gain Enable - 1 = enable, 0 = disable (default)
+
+ This module supports multiple cards and autoprobe.
+
+ Module snd-serial-u16550
+ ------------------------
+
+ Module for UART16550A serial MIDI ports.
+
+ port - port # for UART16550A chip
+ irq - IRQ # for UART16550A chip, -1 = poll mode
+ speed - speed in bauds (9600,19200,38400,57600,115200)
+ 38400 = default
+ base - base for divisor in bauds (57600,115200,230400,460800)
+ 115200 = default
+ outs - number of MIDI ports in a serial port (1-4)
+ 1 = default
+ adaptor - Type of adaptor.
+ 0 = Soundcanvas, 1 = MS-124T, 2 = MS-124W S/A,
+ 3 = MS-124W M/B, 4 = Generic
+
+ This module supports multiple cards. This module does not support autoprobe
+ thus the main port must be specified!!! Other options are optional.
+
+ Module snd-trident
+ ------------------
+
+ Module for Trident 4DWave DX/NX sound cards.
+ * Best Union Miss Melody 4DWave PCI
+ * HIS 4DWave PCI
+ * Warpspeed ONSpeed 4DWave PCI
+ * AzTech PCI 64-Q3D
+ * Addonics SV 750
+ * CHIC True Sound 4Dwave
+ * Shark Predator4D-PCI
+ * Jaton SonicWave 4D
+ * SiS SI7018 PCI Audio
+ * Hoontech SoundTrack Digital 4DWave NX
+
+ pcm_channels - max channels (voices) reserved for PCM
+ wavetable_size - max wavetable size in kB (4-?kb)
+
+ This module supports multiple cards and autoprobe.
+
+ The power-management is supported.
+
+ Module snd-usb-audio
+ --------------------
+
+ Module for USB audio and USB MIDI devices.
+
+ vid - Vendor ID for the device (optional)
+ pid - Product ID for the device (optional)
+ nrpacks - Max. number of packets per URB (default: 8)
+ async_unlink - Use async unlink mode (default: yes)
+ device_setup - Device specific magic number (optional)
+ - Influence depends on the device
+ - Default: 0x0000
+ ignore_ctl_error - Ignore any USB-controller regarding mixer
+ interface (default: no)
+
+ This module supports multiple devices, autoprobe and hotplugging.
+
+ NB: nrpacks parameter can be modified dynamically via sysfs.
+ Don't put the value over 20. Changing via sysfs has no sanity
+ check.
+ NB: async_unlink=0 would cause Oops. It remains just for
+ debugging purpose (if any).
+ NB: ignore_ctl_error=1 may help when you get an error at accessing
+ the mixer element such as URB error -22. This happens on some
+ buggy USB device or the controller.
+
+ Module snd-usb-caiaq
+ --------------------
+
+ Module for caiaq UB audio interfaces,
+ * Native Instruments RigKontrol2
+ * Native Instruments Kore Controller
+ * Native Instruments Audio Kontrol 1
+ * Native Instruments Audio 8 DJ
+
+ This module supports multiple devices, autoprobe and hotplugging.
+
+ Module snd-usb-usx2y
+ --------------------
+
+ Module for Tascam USB US-122, US-224 and US-428 devices.
+
+ This module supports multiple devices, autoprobe and hotplugging.
+
+ Note: you need to load the firmware via usx2yloader utility included
+ in alsa-tools and alsa-firmware packages.
+
+ Module snd-via82xx
+ ------------------
+
+ Module for AC'97 motherboards based on VIA 82C686A/686B, 8233,
+ 8233A, 8233C, 8235, 8237 (south) bridge.
+
+ mpu_port - 0x300,0x310,0x320,0x330, otherwise obtain BIOS setup
+ [VIA686A/686B only]
+ joystick - Enable joystick (default off) [VIA686A/686B only]
+ ac97_clock - AC'97 codec clock base (default 48000Hz)
+ dxs_support - support DXS channels,
+ 0 = auto (default), 1 = enable, 2 = disable,
+ 3 = 48k only, 4 = no VRA, 5 = enable any sample
+ rate and different sample rates on different
+ channels
+ [VIA8233/C, 8235, 8237 only]
+ ac97_quirk - AC'97 workaround for strange hardware
+ See "AC97 Quirk Option" section below.
+
+ This module supports one chip and autoprobe.
+
+ Note: on some SMP motherboards like MSI 694D the interrupts might
+ not be generated properly. In such a case, please try to
+ set the SMP (or MPS) version on BIOS to 1.1 instead of
+ default value 1.4. Then the interrupt number will be
+ assigned under 15. You might also upgrade your BIOS.
+
+ Note: VIA8233/5/7 (not VIA8233A) can support DXS (direct sound)
+ channels as the first PCM. On these channels, up to 4
+ streams can be played at the same time, and the controller
+ can perform sample rate conversion with separate rates for
+ each channel.
+ As default (dxs_support = 0), 48k fixed rate is chosen
+ except for the known devices since the output is often
+ noisy except for 48k on some mother boards due to the
+ bug of BIOS.
+ Please try once dxs_support=5 and if it works on other
+ sample rates (e.g. 44.1kHz of mp3 playback), please let us
+ know the PCI subsystem vendor/device id's (output of
+ "lspci -nv").
+ If dxs_support=5 does not work, try dxs_support=4; if it
+ doesn't work too, try dxs_support=1. (dxs_support=1 is
+ usually for old motherboards. The correct implemented
+ board should work with 4 or 5.) If it still doesn't
+ work and the default setting is ok, dxs_support=3 is the
+ right choice. If the default setting doesn't work at all,
+ try dxs_support=2 to disable the DXS channels.
+ In any cases, please let us know the result and the
+ subsystem vendor/device ids. See "Links and Addresses"
+ below.
+
+ Note: for the MPU401 on VIA823x, use snd-mpu401 driver
+ additionally. The mpu_port option is for VIA686 chips only.
+
+ The power-management is supported.
+
+ Module snd-via82xx-modem
+ ------------------------
+
+ Module for VIA82xx AC97 modem
+
+ ac97_clock - AC'97 codec clock base (default 48000Hz)
+
+ This module supports one card and autoprobe.
+
+ Note: The default index value of this module is -2, i.e. the first
+ slot is excluded.
+
+ The power-management is supported.
+
+ Module snd-virmidi
+ ------------------
+
+ Module for virtual rawmidi devices.
+ This module creates virtual rawmidi devices which communicate
+ to the corresponding ALSA sequencer ports.
+
+ midi_devs - MIDI devices # (1-4, default=4)
+
+ This module supports multiple cards.
+
+ Module snd-virtuoso
+ -------------------
+
+ Module for sound cards based on the Asus AV100/AV200 chips,
+ i.e., Xonar D1, DX, D2, D2X and HDAV1.3 (Deluxe).
+
+ This module supports autoprobe and multiple cards.
+
+ Module snd-vx222
+ ----------------
+
+ Module for Digigram VX-Pocket VX222, V222 v2 and Mic cards.
+
+ mic - Enable Microphone on V222 Mic (NYI)
+ ibl - Capture IBL size. (default = 0, minimum size)
+
+ This module supports multiple cards.
+
+ When the driver is compiled as a module and the hotplug firmware
+ is supported, the firmware data is loaded via hotplug automatically.
+ Install the necessary firmware files in alsa-firmware package.
+ When no hotplug fw loader is available, you need to load the
+ firmware via vxloader utility in alsa-tools package. To invoke
+ vxloader automatically, add the following to /etc/modprobe.conf
+
+ install snd-vx222 /sbin/modprobe --first-time -i snd-vx222 && /usr/bin/vxloader
+
+ (for 2.2/2.4 kernels, add "post-install /usr/bin/vxloader" to
+ /etc/modules.conf, instead.)
+ IBL size defines the interrupts period for PCM. The smaller size
+ gives smaller latency but leads to more CPU consumption, too.
+ The size is usually aligned to 126. As default (=0), the smallest
+ size is chosen. The possible IBL values can be found in
+ /proc/asound/cardX/vx-status proc file.
+
+ The power-management is supported.
+
+ Module snd-vxpocket
+ -------------------
+
+ Module for Digigram VX-Pocket VX2 and 440 PCMCIA cards.
+
+ ibl - Capture IBL size. (default = 0, minimum size)
+
+ This module supports multiple cards. The module is compiled only when
+ PCMCIA is supported on kernel.
+
+ With the older 2.6.x kernel, to activate the driver via the card
+ manager, you'll need to set up /etc/pcmcia/vxpocket.conf. See the
+ sound/pcmcia/vx/vxpocket.c. 2.6.13 or later kernel requires no
+ longer require a config file.
+
+ When the driver is compiled as a module and the hotplug firmware
+ is supported, the firmware data is loaded via hotplug automatically.
+ Install the necessary firmware files in alsa-firmware package.
+ When no hotplug fw loader is available, you need to load the
+ firmware via vxloader utility in alsa-tools package.
+
+ About capture IBL, see the description of snd-vx222 module.
+
+ Note: snd-vxp440 driver is merged to snd-vxpocket driver since
+ ALSA 1.0.10.
+
+ The power-management is supported.
+
+ Module snd-ymfpci
+ -----------------
+
+ Module for Yamaha PCI chips (YMF72x, YMF74x & YMF75x).
+
+ mpu_port - 0x300,0x330,0x332,0x334, 0 (disable) by default,
+ 1 (auto-detect for YMF744/754 only)
+ fm_port - 0x388,0x398,0x3a0,0x3a8, 0 (disable) by default
+ 1 (auto-detect for YMF744/754 only)
+ joystick_port - 0x201,0x202,0x204,0x205, 0 (disable) by default,
+ 1 (auto-detect)
+ rear_switch - enable shared rear/line-in switch (bool)
+
+ This module supports autoprobe and multiple chips.
+
+ The power-management is supported.
+
+ Module snd-pdaudiocf
+ --------------------
+
+ Module for Sound Core PDAudioCF sound card.
+
+ The power-management is supported.
+
+
+AC97 Quirk Option
+=================
+
+The ac97_quirk option is used to enable/override the workaround for
+specific devices on drivers for on-board AC'97 controllers like
+snd-intel8x0. Some hardware have swapped output pins between Master
+and Headphone, or Surround (thanks to confusion of AC'97
+specifications from version to version :-)
+
+The driver provides the auto-detection of known problematic devices,
+but some might be unknown or wrongly detected. In such a case, pass
+the proper value with this option.
+
+The following strings are accepted:
+ - default Don't override the default setting
+ - none Disable the quirk
+ - hp_only Bind Master and Headphone controls as a single control
+ - swap_hp Swap headphone and master controls
+ - swap_surround Swap master and surround controls
+ - ad_sharing For AD1985, turn on OMS bit and use headphone
+ - alc_jack For ALC65x, turn on the jack sense mode
+ - inv_eapd Inverted EAPD implementation
+ - mute_led Bind EAPD bit for turning on/off mute LED
+
+For backward compatibility, the corresponding integer value -1, 0,
+... are accepted, too.
+
+For example, if "Master" volume control has no effect on your device
+but only "Headphone" does, pass ac97_quirk=hp_only module option.
+
+
+Configuring Non-ISAPNP Cards
+============================
+
+When the kernel is configured with ISA-PnP support, the modules
+supporting the isapnp cards will have module options "isapnp".
+If this option is set, *only* the ISA-PnP devices will be probed.
+For probing the non ISA-PnP cards, you have to pass "isapnp=0" option
+together with the proper i/o and irq configuration.
+
+When the kernel is configured without ISA-PnP support, isapnp option
+will be not built in.
+
+
+Module Autoloading Support
+==========================
+
+The ALSA drivers can be loaded automatically on demand by defining
+module aliases. The string 'snd-card-%1' is requested for ALSA native
+devices where %i is sound card number from zero to seven.
+
+To auto-load an ALSA driver for OSS services, define the string
+'sound-slot-%i' where %i means the slot number for OSS, which
+corresponds to the card index of ALSA. Usually, define this
+as the same card module.
+
+An example configuration for a single emu10k1 card is like below:
+----- /etc/modprobe.conf
+alias snd-card-0 snd-emu10k1
+alias sound-slot-0 snd-emu10k1
+----- /etc/modprobe.conf
+
+The available number of auto-loaded sound cards depends on the module
+option "cards_limit" of snd module. As default it's set to 1.
+To enable the auto-loading of multiple cards, specify the number of
+sound cards in that option.
+
+When multiple cards are available, it'd better to specify the index
+number for each card via module option, too, so that the order of
+cards is kept consistent.
+
+An example configuration for two sound cards is like below:
+
+----- /etc/modprobe.conf
+# ALSA portion
+options snd cards_limit=2
+alias snd-card-0 snd-interwave
+alias snd-card-1 snd-ens1371
+options snd-interwave index=0
+options snd-ens1371 index=1
+# OSS/Free portion
+alias sound-slot-0 snd-interwave
+alias sound-slot-1 snd-ens1371
+----- /etc/modprobe.conf
+
+In this example, the interwave card is always loaded as the first card
+(index 0) and ens1371 as the second (index 1).
+
+Alternative (and new) way to fixate the slot assignment is to use
+"slots" option of snd module. In the case above, specify like the
+following:
+
+options snd slots=snd-interwave,snd-ens1371
+
+Then, the first slot (#0) is reserved for snd-interwave driver, and
+the second (#1) for snd-ens1371. You can omit index option in each
+driver if slots option is used (although you can still have them at
+the same time as long as they don't conflict).
+
+The slots option is especially useful for avoiding the possible
+hot-plugging and the resultant slot conflict. For example, in the
+case above again, the first two slots are already reserved. If any
+other driver (e.g. snd-usb-audio) is loaded before snd-interwave or
+snd-ens1371, it will be assigned to the third or later slot.
+
+When a module name is given with '!', the slot will be given for any
+modules but that name. For example, "slots=!snd-pcsp" will reserve
+the first slot for any modules but snd-pcsp.
+
+
+ALSA PCM devices to OSS devices mapping
+=======================================
+
+/dev/snd/pcmC0D0[c|p] -> /dev/audio0 (/dev/audio) -> minor 4
+/dev/snd/pcmC0D0[c|p] -> /dev/dsp0 (/dev/dsp) -> minor 3
+/dev/snd/pcmC0D1[c|p] -> /dev/adsp0 (/dev/adsp) -> minor 12
+/dev/snd/pcmC1D0[c|p] -> /dev/audio1 -> minor 4+16 = 20
+/dev/snd/pcmC1D0[c|p] -> /dev/dsp1 -> minor 3+16 = 19
+/dev/snd/pcmC1D1[c|p] -> /dev/adsp1 -> minor 12+16 = 28
+/dev/snd/pcmC2D0[c|p] -> /dev/audio2 -> minor 4+32 = 36
+/dev/snd/pcmC2D0[c|p] -> /dev/dsp2 -> minor 3+32 = 39
+/dev/snd/pcmC2D1[c|p] -> /dev/adsp2 -> minor 12+32 = 44
+
+The first number from /dev/snd/pcmC{X}D{Y}[c|p] expression means
+sound card number and second means device number. The ALSA devices
+have either 'c' or 'p' suffix indicating the direction, capture and
+playback, respectively.
+
+Please note that the device mapping above may be varied via the module
+options of snd-pcm-oss module.
+
+
+Proc interfaces (/proc/asound)
+==============================
+
+/proc/asound/card#/pcm#[cp]/oss
+-------------------------------
+ String "erase" - erase all additional informations about OSS applications
+ String "<app_name> <fragments> <fragment_size> [<options>]"
+
+ <app_name> - name of application with (higher priority) or without path
+ <fragments> - number of fragments or zero if auto
+ <fragment_size> - size of fragment in bytes or zero if auto
+ <options> - optional parameters
+ - disable the application tries to open a pcm device for
+ this channel but does not want to use it.
+ (Cause a bug or mmap needs)
+ It's good for Quake etc...
+ - direct don't use plugins
+ - block force block mode (rvplayer)
+ - non-block force non-block mode
+ - whole-frag write only whole fragments (optimization affecting
+ playback only)
+ - no-silence do not fill silence ahead to avoid clicks
+ - buggy-ptr Returns the whitespace blocks in GETOPTR ioctl
+ instead of filled blocks
+
+ Example: echo "x11amp 128 16384" > /proc/asound/card0/pcm0p/oss
+ echo "squake 0 0 disable" > /proc/asound/card0/pcm0c/oss
+ echo "rvplayer 0 0 block" > /proc/asound/card0/pcm0p/oss
+
+
+Early Buffer Allocation
+=======================
+
+Some drivers (e.g. hdsp) require the large contiguous buffers, and
+sometimes it's too late to find such spaces when the driver module is
+actually loaded due to memory fragmentation. You can pre-allocate the
+PCM buffers by loading snd-page-alloc module and write commands to its
+proc file in prior, for example, in the early boot stage like
+/etc/init.d/*.local scripts.
+
+Reading the proc file /proc/drivers/snd-page-alloc shows the current
+usage of page allocation. In writing, you can send the following
+commands to the snd-page-alloc driver:
+
+ - add VENDOR DEVICE MASK SIZE BUFFERS
+
+ VENDOR and DEVICE are PCI vendor and device IDs. They take
+ integer numbers (0x prefix is needed for the hex).
+ MASK is the PCI DMA mask. Pass 0 if not restricted.
+ SIZE is the size of each buffer to allocate. You can pass
+ k and m suffix for KB and MB. The max number is 16MB.
+ BUFFERS is the number of buffers to allocate. It must be greater
+ than 0. The max number is 4.
+
+ - erase
+
+ This will erase the all pre-allocated buffers which are not in
+ use.
+
+
+Links and Addresses
+===================
+
+ ALSA project homepage
+ http://www.alsa-project.org
+
+ ALSA Bug Tracking System
+ https://bugtrack.alsa-project.org/bugs/
+
+ ALSA Developers ML
+ mailto:alsa-devel@alsa-project.org
diff --git a/Documentation/sound/alsa/Audigy-mixer.txt b/Documentation/sound/alsa/Audigy-mixer.txt
new file mode 100644
index 0000000..7f10dc6
--- /dev/null
+++ b/Documentation/sound/alsa/Audigy-mixer.txt
@@ -0,0 +1,345 @@
+
+ Sound Blaster Audigy mixer / default DSP code
+ ===========================================
+
+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.
+(This article does not deal with the overall functionality of the
+EMU10K2 chips. See the manuals section for further details.)
+
+The ALSA driver programs this portion of chip by default code
+(can be altered later) which offers the following functionality:
+
+
+1) 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
+here. Note that the controls work as attenuators: the maximum value is the
+neutral position leaving the signal unchanged. Note that if the same destination
+is mentioned in multiple controls, the signal is accumulated and can be wrapped
+(set to maximal or minimal value without checking of overflow).
+
+
+Explanation of used abbreviations:
+
+DAC - digital to analog converter
+ADC - analog to digital converter
+I2S - one-way three wire serial bus for digital sound by Philips Semiconductors
+ (this standard is used for connecting standalone DAC and ADC converters)
+LFE - low frequency effects (subwoofer signal)
+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
+------------------------------
+
+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)
+ 1 - left, 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
+ 1 - mono, B destination (FX-bus 0-63), default 1
+ 2 - mono, C destination (FX-bus 0-63), default 2
+ 3 - mono, D destination (FX-bus 0-63), default 3
+ 4 - mono, E 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
+ 7 - mono, H 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
+ 10 - left, C destination (FX-bus 0-63), default 2
+ 11 - left, D destination (FX-bus 0-63), default 3
+ 12 - left, E 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
+ 15 - left, H 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
+ 18 - right, C destination (FX-bus 0-63), default 2
+ 19 - right, D destination (FX-bus 0-63), default 3
+ 20 - right, E 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
+ 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)
+ 1 - mono, B destination attn, default 255 (no attenuation)
+ 2 - mono, C destination attn, default 0 (mute)
+ 3 - mono, D destination attn, default 0 (mute)
+ 4 - mono, E destination attn, default 0 (mute)
+ 5 - mono, F destination attn, default 0 (mute)
+ 6 - mono, G destination attn, default 0 (mute)
+ 7 - mono, H destination attn, default 0 (mute)
+ 8 - left, A destination attn, default 255 (no attenuation)
+ 9 - left, B destination attn, default 0 (mute)
+ 10 - left, C destination attn, default 0 (mute)
+ 11 - left, D destination attn, default 0 (mute)
+ 12 - left, E destination attn, default 0 (mute)
+ 13 - left, F destination attn, default 0 (mute)
+ 14 - left, G destination attn, default 0 (mute)
+ 15 - left, H destination attn, default 0 (mute)
+ 16 - right, A destination attn, default 0 (mute)
+ 17 - right, B destination attn, default 255 (no attenuation)
+ 18 - right, C destination attn, default 0 (mute)
+ 19 - right, D destination attn, default 0 (mute)
+ 20 - right, E destination attn, default 0 (mute)
+ 21 - right, F destination attn, default 0 (mute)
+ 22 - right, G destination attn, default 0 (mute)
+ 23 - right, H destination attn, default 0 (mute)
+
+
+
+4) MANUALS/PATENTS:
+-------------------
+
+ftp://opensource.creative.com/pub/doc
+-------------------------------------
+
+ Files:
+ LM4545.pdf AC97 Codec
+
+ m2049.pdf The EMU10K1 Digital Audio Processor
+
+ 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 9901953 (A1) 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 5928342 Audio Effects Processor integrated on a single chip (Jul. 27, 1999)
+ with a multiport memory onto which multiple asynchronous
+ digital sound samples can be concurrently loaded
+
+ US 5930158 Processor with Instruction Set for Audio Effects (Jul. 27, 1999)
+
+ US 6032235 Memory initialization circuit (Tram) (Feb. 29, 2000)
+
+ US 6138207 Interpolation looping of audio samples in cache connected to (Oct. 24, 2000)
+ system bus with prioritization and modification of bus transfers
+ in accordance with loop ends and minimum block sizes
+
+ US 6151670 Method for conserving memory storage using a (Nov. 21, 2000)
+ pool of short term memory registers
+
+ US 6195715 Interrupt control for multiple programs communicating with (Feb. 27, 2001)
+ a common interrupt by associating programs to GP registers,
+ defining interrupt register, polling GP registers, and invoking
+ callback routine associated with defined interrupt register
diff --git a/Documentation/sound/alsa/Audiophile-Usb.txt b/Documentation/sound/alsa/Audiophile-Usb.txt
new file mode 100644
index 0000000..a4c53d8
--- /dev/null
+++ b/Documentation/sound/alsa/Audiophile-Usb.txt
@@ -0,0 +1,442 @@
+ Guide to using M-Audio Audiophile USB with ALSA and Jack 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>
+ - Modifying document structure
+* v1.5 - Thibault Le Meur (2007-07-12)
+ - Added AC3/DTS passthru info
+
+
+1 - 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)
+ * Midi In (Mi)
+ * 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"
+
+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
+ - 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
+ - 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
+ - As a consequence, the Di port must be enable only if an active Digital
+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)
+
+
+2 - 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
+========================================
+
+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".
+
+3.1 - 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
+by the applications: for instance if the user is recording in a
+24bit-depth-mode and immediately after wants to switch to a 16bit-depth mode,
+the snd-usb-audio module will reconfigure the device on the fly.
+
+This approach has the advantage to let the driver automatically switch from sample
+rates/depths automatically according to the user's needs. However, those who
+are using the device under windows know that this is not how the device is meant to
+work: under windows applications must be closed before using the m-audio control
+panel to switch the device working mode. Thus as we'll see in next section, this
+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
+
+In this mode, the device uses Big Endian byte-encoding so that
+supported audio format are S16_BE for 16-bit depth modes and S24_3BE for
+24-bits depth mode.
+
+One exception is the hw:1,2 port which was reported to be Little Endian
+compliant (supposedly supporting S16_LE) but processes in fact only S16_BE streams.
+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
+ % aplay -D hw:1,0 -c2 -t raw -r48000 -fS24_3BE test.raw
+ * 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
+ % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_BE test.raw
+ * 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
+---------------------------
+
+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
+device. For instance, a particularly annoying issue is that the sound captured
+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
+release 2.6.17)
+
+3.2.1 - 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
+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
+
+The two supported modes are:
+
+ * 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
+ - 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
+ - hw:1,2 is not available
+
+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
+
+The three supported modes are:
+
+ * 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
+ - 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
+ - 24bits 96kHz mode
+ - Di is enabled by default for this mode but does not need to be connected
+ to an active source
+ - Only 1 port from {Ai,Ao,Di,Do} can be used at the same time
+ - hw:1,0 is available in captured mode
+ - hw:1,2 is not available
+
+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
+
+Thanks to Hakan Lennestal, I now have a report saying that this mode works.
+
+ * 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
+----------------------------------------------
+
+The parameter can be given:
+
+ * 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
+ - For Fedora distributions, edit the /etc/modprobe.conf file:
+ alias snd-card-1 snd-usb-audio
+ options snd-usb-audio index=1 device_setup=0x09
+
+CAUTION when initializing the device
+-------------------------------------
+
+ * Correct initialization on the device requires that device_setup is given to
+ the module BEFORE the device is turned on. So, if you use the "manual probing"
+ method described above, take care to power-on the device AFTER this initialization.
+
+ * Failing to respect this will lead to a misconfiguration of the device. In this case
+ turn off the device, unprobe the snd-usb-audio module, then probe it again with
+ correct device_setup parameter and then (and only then) turn on the device again.
+
+ * 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.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
+-------------------------------------
+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
+
+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|
+ +---+---+---+---+---+---+---+---+
+ | 0 | 0 | 0 | Di|24B|96K|DTS|SET|
+ +---+---+---+---+---+---+---+---+
+
+Where:
+ * b0 is the "SET" bit
+ - it MUST be set if device_setup is initialized
+ * 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
+ - Otherwise the sample rate range is 8-48kHz
+ * b3 is the bit depth selection flag
+ - 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
+ 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"
+ - 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
+
+You may safely skip this section if you're not interested in driver
+hacking.
+
+This section describes some internal aspects of the device and summarizes the
+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
+ - 24-bit depth, 48.1-96kHz sample mode
+ - Adaptive playback (Ao and Do), Synch capture (Ai), or Asynch capture (Di)
+ * AltSettings 2 corresponds to
+ - 24-bit depth, 8-48kHz sample mode
+ - Asynch capture and playback (Ao,Ai,Do,Di)
+ * AltSettings 3 corresponds to
+ - 24-bit depth, 8-48kHz sample mode
+ - Synch capture (Ai) and Adaptive playback (Ao,Do)
+ * AltSettings 4 corresponds to
+ - 16-bit depth, 8-48kHz sample mode
+ - Asynch capture and playback (Ao,Ai,Do,Di)
+ * AltSettings 5 corresponds to
+ - 16-bit depth, 8-48kHz sample mode
+ - Synch capture (Ai) and Adaptive playback (Ao,Do)
+ * 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:
+ * 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
+ * if samples are using 24bits/48KHz then AltSet 2 must me used if
+ Digital input is connected, and only AltSet nb.3 if Digital input
+ is not connected
+ * if samples are using 16bits/48KHz then AltSet 4 must me used if
+ Digital input is connected, and only AltSet nb.5 if Digital input
+ is not connected
+
+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
+corresponding to device_setup from being registered in the driver.
+
+4 - 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
+-----------------------------
+
+Jack supports big endian devices only in recent versions (thanks to
+Andreas Steinmetz for his first big-endian patch). I can't remember
+exactly when this support was released into jackd, let's just say that
+with jackd version 0.103.0 it's almost ok (just a small bug is affecting
+16bits Big-Endian devices, but since you've read carefully the above
+paragraphs, you're now using kernel >= 2.6.23 and your 16bits devices
+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
+-----------------------
+If you don't have a recent Jackd installed, you can downgrade to using
+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
+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."
+
+4.3 - 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)
+
+If you want to get Ai+Di and/or Ao+Do support with Jack, you would need to
+combine the Alsa devices into one logical "complex" device.
+
+If you want to give it a try, I recommend reading the information from
+this page: http://www.sound-man.co.uk/linuxaudio/ice1712multi.html
+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
+ file
+* start jackd with this device
+
+I had no success in testing this for now, if you have any success with this kind
+of setup, please drop me an email.
diff --git a/Documentation/sound/alsa/Bt87x.txt b/Documentation/sound/alsa/Bt87x.txt
new file mode 100644
index 0000000..f158cde
--- /dev/null
+++ b/Documentation/sound/alsa/Bt87x.txt
@@ -0,0 +1,78 @@
+Intro
+=====
+
+You might have noticed that the bt878 grabber cards have actually
+_two_ PCI functions:
+
+$ lspci
+[ ... ]
+00:0a.0 Multimedia video 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
+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...
+
+Some cards do not bother to connect anything to the audio input pins of
+the chip, and some other cards use the audio function to transport MPEG
+video data, so it's quite possible that audio recording may not work
+with your card.
+
+
+Driver Status
+=============
+
+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
+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
+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
+<alsa-devel@alsa-project.org>, regardless of whether audio capture works
+or not, so that future versions of this driver know about your card.
+
+
+Audio modes
+===========
+
+The chip knows two different modes (digital/analog). snd-bt87x
+registers two PCM devices, one for each mode. They cannot be used at
+the same time.
+
+
+Digital audio mode
+==================
+
+The first device (hw:X,0) gives you 16 bit stereo sound. The sample
+rate depends on the external source which feeds the Bt87x with digital
+sound via I2S interface.
+
+
+Analog audio mode (A/D)
+=======================
+
+The second device (hw:X,1) gives you 8 or 16 bit mono sound. Supported
+sample rates are between 119466 and 448000 Hz (yes, these numbers are
+that high). If you've set the CONFIG_SND_BT87X_OVERCLOCK option, the
+maximum sample rate is 1792000 Hz, but audio data becomes unusable
+beyond 896000 Hz on my card.
+
+The chip has three analog inputs. Consequently you'll get a mixer
+device to control these.
+
+
+Have fun,
+
+ Clemens
+
+
+Written by Clemens Ladisch <clemens@ladisch.de>
+big parts copied from btaudio.txt by Gerd Knorr <kraxel@bytesex.org>
diff --git a/Documentation/sound/alsa/CMIPCI.txt b/Documentation/sound/alsa/CMIPCI.txt
new file mode 100644
index 0000000..16935c8
--- /dev/null
+++ b/Documentation/sound/alsa/CMIPCI.txt
@@ -0,0 +1,254 @@
+ Brief Notes on C-Media 8338/8738/8768/8770 Driver
+ =================================================
+
+ Takashi Iwai <tiwai@suse.de>
+
+
+Front/Rear Multi-channel Playback
+---------------------------------
+
+CM8x38 chip can use ADC as the second DAC so that two different stereo
+channels can be used for front/rear playbacks. Since there are two
+DACs, both streams are handled independently unlike the 4/6ch multi-
+channel playbacks in the section below.
+
+As default, ALSA driver assigns the first PCM device (i.e. hw:0,0 for
+card#0) for front and 4/6ch playbacks, while the second PCM device
+(hw:0,1) is assigned to the second DAC for rear playback.
+
+There are slight differences between the two DACs:
+
+- The first DAC supports U8 and S16LE formats, while the second DAC
+ supports only S16LE.
+- The second DAC supports only two channel stereo.
+
+Please note that the CM8x38 DAC doesn't support continuous playback
+rate but only fixed rates: 5512, 8000, 11025, 16000, 22050, 32000,
+44100 and 48000 Hz.
+
+The rear output can be heard only when "Four Channel Mode" switch is
+disabled. Otherwise no signal will be routed to the rear speakers.
+As default it's turned on.
+
+*** WARNING ***
+When "Four Channel Mode" switch is off, the output from rear speakers
+will be FULL VOLUME regardless of Master and PCM volumes.
+This might damage your audio equipment. Please disconnect speakers
+before your turn off this switch.
+*** WARNING ***
+
+[ Well.. I once got the output with correct volume (i.e. same with the
+ front one) and was so excited. It was even with "Four Channel" bit
+ on and "double DAC" mode. Actually I could hear separate 4 channels
+ from front and rear speakers! But.. after reboot, all was gone.
+ It's a very pity that I didn't save the register dump at that
+ time.. Maybe there is an unknown register to achieve this... ]
+
+If your card has an extra output jack for the rear output, the rear
+playback should be routed there as default. If not, there is a
+control switch in the driver "Line-In As Rear", which you can change
+via alsamixer or somewhat else. When this switch is on, line-in jack
+is used as rear output.
+
+There are two more controls regarding to the rear output.
+The "Exchange DAC" switch is used to exchange front and rear playback
+routes, i.e. the 2nd DAC is output from front output.
+
+
+4/6 Multi-Channel Playback
+--------------------------
+
+The recent CM8738 chips support for the 4/6 multi-channel playback
+function. This is useful especially for AC3 decoding.
+
+When the multi-channel is supported, the driver name has a suffix
+"-MC" such like "CMI8738-MC6". You can check this name from
+/proc/asound/cards.
+
+When the 4/6-ch output is enabled, the second DAC accepts up to 6 (or
+4) channels. While the dual DAC supports two different rates or
+formats, the 4/6-ch playback supports only the same condition for all
+channels. Since the multi-channel playback mode uses both DACs, you
+cannot operate with full-duplex.
+
+The 4.0 and 5.1 modes are defined as the pcm "surround40" and "surround51"
+in alsa-lib. For example, you can play a WAV file with 6 channels like
+
+ % aplay -Dsurround51 sixchannels.wav
+
+For programming the 4/6 channel playback, you need to specify the PCM
+channels as you like and set the format S16LE. For example, for playback
+with 4 channels,
+
+ snd_pcm_hw_params_set_access(pcm, hw, SND_PCM_ACCESS_RW_INTERLEAVED);
+ // or mmap if you like
+ snd_pcm_hw_params_set_format(pcm, hw, SND_PCM_FORMAT_S16_LE);
+ snd_pcm_hw_params_set_channels(pcm, hw, 4);
+
+and use the interleaved 4 channel data.
+
+There are some control switchs affecting to the speaker connections:
+
+"Line-In Mode" - an enum control to change the behavior of line-in
+ jack. Either "Line-In", "Rear Output" or "Bass Output" can
+ be selected. The last item is available only with model 039
+ or newer.
+ When "Rear Output" is chosen, the surround channels 3 and 4
+ are output to line-in jack.
+"Mic-In Mode" - an enum control to change the behavior of mic-in
+ jack. Either "Mic-In" or "Center/LFE Output" can be
+ selected.
+ When "Center/LFE Output" is chosen, the center and bass
+ channels (channels 5 and 6) are output to mic-in jack.
+
+Digital I/O
+-----------
+
+The CM8x38 provides the excellent SPDIF capability with very cheap
+price (yes, that's the reason I bought the card :)
+
+The SPDIF playback and capture are done via the third PCM device
+(hw:0,2). Usually this is assigned to the PCM device "spdif".
+The available rates are 44100 and 48000 Hz.
+For playback with aplay, you can run like below:
+
+ % aplay -Dhw:0,2 foo.wav
+
+or
+
+ % aplay -Dspdif foo.wav
+
+24bit format is also supported experimentally.
+
+The playback and capture over SPDIF use normal DAC and ADC,
+respectively, so you cannot playback both analog and digital streams
+simultaneously.
+
+To enable SPDIF output, you need to turn on "IEC958 Output Switch"
+control via mixer or alsactl ("IEC958" is the official name of
+so-called S/PDIF). Then you'll see the red light on from the card so
+you know that's working obviously :)
+The SPDIF input is always enabled, so you can hear SPDIF input data
+from line-out with "IEC958 In Monitor" switch at any time (see
+below).
+
+You can play via SPDIF even with the first device (hw:0,0),
+but SPDIF is enabled only when the proper format (S16LE), sample rate
+(441100 or 48000) and channels (2) are used. Otherwise it's turned
+off. (Also don't forget to turn on "IEC958 Output Switch", too.)
+
+
+Additionally there are relevant control switches:
+
+"IEC958 Mix Analog" - Mix analog PCM playback and FM-OPL/3 streams and
+ output through SPDIF. This switch appears only on old chip
+ models (CM8738 033 and 037).
+ Note: without this control you can output PCM to SPDIF.
+ This is "mixing" of streams, so e.g. it's not for AC3 output
+ (see the next section).
+
+"IEC958 In Select" - Select SPDIF input, the internal CD-in (false)
+ and the external input (true).
+
+"IEC958 Loop" - SPDIF input data is loop back into SPDIF
+ output (aka bypass)
+
+"IEC958 Copyright" - Set the copyright bit.
+
+"IEC958 5V" - Select 0.5V (coax) or 5V (optical) interface.
+ On some cards this doesn't work and you need to change the
+ configuration with hardware dip-switch.
+
+"IEC958 In Monitor" - SPDIF input is routed to DAC.
+
+"IEC958 In Phase Inverse" - Set SPDIF input format as inverse.
+ [FIXME: this doesn't work on all chips..]
+
+"IEC958 In Valid" - Set input validity flag detection.
+
+Note: When "PCM Playback Switch" is on, you'll hear the digital output
+stream through analog line-out.
+
+
+The AC3 (RAW DIGITAL) OUTPUT
+----------------------------
+
+The driver supports raw digital (typically AC3) i/o over SPDIF. This
+can be toggled via IEC958 playback control, but usually you need to
+access it via alsa-lib. See alsa-lib documents for more details.
+
+On the raw digital mode, the "PCM Playback Switch" is automatically
+turned off so that non-audio data is heard from the analog line-out.
+Similarly the following switches are off: "IEC958 Mix Analog" and
+"IEC958 Loop". The switches are resumed after closing the SPDIF PCM
+device automatically to the previous state.
+
+On the model 033, AC3 is implemented by the software conversion in
+the alsa-lib. If you need to bypass the software conversion of IEC958
+subframes, pass the "soft_ac3=0" module option. This doesn't matter
+on the newer models.
+
+
+ANALOG MIXER INTERFACE
+----------------------
+
+The mixer interface on CM8x38 is similar to SB16.
+There are Master, PCM, Synth, CD, Line, Mic and PC Speaker playback
+volumes. Synth, CD, Line and Mic have playback and capture switches,
+too, as well as SB16.
+
+In addition to the standard SB mixer, CM8x38 provides more functions.
+- PCM playback switch
+- PCM capture switch (to capture the data sent to DAC)
+- Mic Boost switch
+- Mic capture volume
+- Aux playback volume/switch and capture switch
+- 3D control switch
+
+
+MIDI CONTROLLER
+---------------
+
+With CMI8338 chips, the MPU401-UART interface is disabled as default.
+You need to set the module option "mpu_port" to a valid I/O port address
+to enable MIDI support. Valid I/O ports are 0x300, 0x310, 0x320 and
+0x330. Choose a value that doesn't conflict with other cards.
+
+With CMI8738 and newer chips, the MIDI interface is enabled by default
+and the driver automatically chooses a port address.
+
+There is _no_ hardware wavetable function on this chip (except for
+OPL3 synth below).
+What's said as MIDI synth on Windows is a software synthesizer
+emulation. On Linux use TiMidity or other softsynth program for
+playing MIDI music.
+
+
+FM OPL/3 Synth
+--------------
+
+The FM OPL/3 is also enabled as default only for the first card.
+Set "fm_port" module option for more cards.
+
+The output quality of FM OPL/3 is, however, very weird.
+I don't know why..
+
+CMI8768 and newer chips do not have the FM synth.
+
+
+Joystick and Modem
+------------------
+
+The legacy joystick is supported. To enable the joystick support, pass
+joystick_port=1 module option. The value 1 means the auto-detection.
+If the auto-detection fails, try to pass the exact I/O address.
+
+The modem is enabled dynamically via a card control switch "Modem".
+
+
+Debugging Information
+---------------------
+
+The registers are shown in /proc/asound/cardX/cmipci. If you have any
+problem (especially unexpected behavior of mixer), please attach the
+output of this proc file together with the bug report.
diff --git a/Documentation/sound/alsa/ControlNames.txt b/Documentation/sound/alsa/ControlNames.txt
new file mode 100644
index 0000000..5b18298
--- /dev/null
+++ b/Documentation/sound/alsa/ControlNames.txt
@@ -0,0 +1,84 @@
+This document describes standard names of mixer controls.
+
+Syntax: SOURCE [DIRECTION] FUNCTION
+
+DIRECTION:
+ <nothing> (both directions)
+ Playback
+ Capture
+ Bypass Playback
+ Bypass Capture
+
+FUNCTION:
+ Switch (on/off switch)
+ Volume
+ Route (route control, hardware specific)
+
+SOURCE:
+ Master
+ Master Mono
+ Hardware Master
+ Headphone
+ PC Speaker
+ Phone
+ Phone Input
+ Phone Output
+ Synth
+ FM
+ Mic
+ Line
+ CD
+ Video
+ Zoom Video
+ Aux
+ PCM
+ PCM Front
+ PCM Rear
+ 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
+
+Exceptions:
+ [Digital] Capture Source
+ [Digital] Capture Switch (aka input gain switch)
+ [Digital] Capture Volume (aka input gain volume)
+ [Digital] Playback Switch (aka output gain switch)
+ [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) */
diff --git a/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl b/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl
new file mode 100644
index 0000000..9d644f7
--- /dev/null
+++ b/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl
@@ -0,0 +1,100 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<book>
+<?dbhtml filename="index.html">
+
+<!-- ****************************************************** -->
+<!-- Header -->
+<!-- ****************************************************** -->
+ <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>
+
+ <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
+ </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>
+ </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>
+ </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>Miscellaneous Functions</title>
+ <sect1><title>Hardware-Dependent Devices API</title>
+!Esound/core/hwdep.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>
diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
new file mode 100644
index 0000000..87a7c07
--- /dev/null
+++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
@@ -0,0 +1,6210 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<book>
+<?dbhtml filename="index.html">
+
+<!-- ****************************************************** -->
+<!-- Header -->
+<!-- ****************************************************** -->
+ <bookinfo>
+ <title>Writing an ALSA Driver</title>
+ <author>
+ <firstname>Takashi</firstname>
+ <surname>Iwai</surname>
+ <affiliation>
+ <address>
+ <email>tiwai@suse.de</email>
+ </address>
+ </affiliation>
+ </author>
+
+ <date>Oct 15, 2007</date>
+ <edition>0.3.7</edition>
+
+ <abstract>
+ <para>
+ This document describes how to write an ALSA (Advanced Linux
+ Sound Architecture) driver.
+ </para>
+ </abstract>
+
+ <legalnotice>
+ <para>
+ Copyright (c) 2002-2005 Takashi Iwai <email>tiwai@suse.de</email>
+ </para>
+
+ <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>
+
+<!-- ****************************************************** -->
+<!-- Preface -->
+<!-- ****************************************************** -->
+ <preface id="preface">
+ <title>Preface</title>
+ <para>
+ This document describes how to write an
+ <ulink url="http://www.alsa-project.org/"><citetitle>
+ ALSA (Advanced Linux Sound Architecture)</citetitle></ulink>
+ driver. The document focuses mainly on PCI soundcards.
+ In the case of other device types, the API might
+ be different, too. However, at least the ALSA kernel API is
+ consistent, and therefore it would be still a bit help for
+ writing them.
+ </para>
+
+ <para>
+ This document targets people who already have enough
+ C language skills and have basic linux kernel programming
+ knowledge. This document doesn't explain the general
+ topic of linux kernel coding and doesn't cover low-level
+ driver implementation details. It only describes
+ the standard way to write a PCI sound driver on ALSA.
+ </para>
+
+ <para>
+ If you are already familiar with the older ALSA ver.0.5.x API, you
+ can check the drivers such as <filename>sound/pci/es1938.c</filename> or
+ <filename>sound/pci/maestro3.c</filename> which have also almost the same
+ code-base in the ALSA 0.5.x tree, so you can compare the differences.
+ </para>
+
+ <para>
+ This document is still a draft version. Any feedback and
+ corrections, please!!
+ </para>
+ </preface>
+
+
+<!-- ****************************************************** -->
+<!-- File Tree Structure -->
+<!-- ****************************************************** -->
+ <chapter id="file-tree">
+ <title>File Tree Structure</title>
+
+ <section id="file-tree-general">
+ <title>General</title>
+ <para>
+ The ALSA drivers are provided in two ways.
+ </para>
+
+ <para>
+ One is the trees provided as a tarball or via cvs from the
+ ALSA's ftp site, and another is the 2.6 (or later) Linux kernel
+ tree. To synchronize both, the ALSA driver tree is split into
+ two different trees: alsa-kernel and alsa-driver. The former
+ contains purely the source code for the Linux 2.6 (or later)
+ tree. This tree is designed only for compilation on 2.6 or
+ later environment. The latter, alsa-driver, contains many subtle
+ files for compiling ALSA drivers outside of the Linux kernel tree,
+ wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API,
+ and additional drivers which are still in development or in
+ tests. The drivers in alsa-driver tree will be moved to
+ alsa-kernel (and eventually to the 2.6 kernel tree) when they are
+ finished and confirmed to work fine.
+ </para>
+
+ <para>
+ The file tree structure of ALSA driver is depicted below. Both
+ alsa-kernel and alsa-driver have almost the same file
+ structure, except for <quote>core</quote> directory. It's
+ named as <quote>acore</quote> in alsa-driver tree.
+
+ <example>
+ <title>ALSA File Tree Structure</title>
+ <literallayout>
+ sound
+ /core
+ /oss
+ /seq
+ /oss
+ /instr
+ /ioctl32
+ /include
+ /drivers
+ /mpu401
+ /opl3
+ /i2c
+ /l3
+ /synth
+ /emux
+ /pci
+ /(cards)
+ /isa
+ /(cards)
+ /arm
+ /ppc
+ /sparc
+ /usb
+ /pcmcia /(cards)
+ /oss
+ </literallayout>
+ </example>
+ </para>
+ </section>
+
+ <section id="file-tree-core-directory">
+ <title>core directory</title>
+ <para>
+ This directory contains the middle layer which is the heart
+ of ALSA drivers. In this directory, the native ALSA modules are
+ stored. The sub-directories contain different modules and are
+ dependent upon the kernel config.
+ </para>
+
+ <section id="file-tree-core-directory-oss">
+ <title>core/oss</title>
+
+ <para>
+ The codes for PCM and mixer OSS emulation modules are stored
+ in this directory. The rawmidi OSS emulation is included in
+ the ALSA rawmidi code since it's quite small. The sequencer
+ code is stored in <filename>core/seq/oss</filename> directory (see
+ <link linkend="file-tree-core-directory-seq-oss"><citetitle>
+ below</citetitle></link>).
+ </para>
+ </section>
+
+ <section id="file-tree-core-directory-ioctl32">
+ <title>core/ioctl32</title>
+
+ <para>
+ This directory contains the 32bit-ioctl wrappers for 64bit
+ architectures such like x86-64, ppc64 and sparc64. For 32bit
+ and alpha architectures, these are not compiled.
+ </para>
+ </section>
+
+ <section id="file-tree-core-directory-seq">
+ <title>core/seq</title>
+ <para>
+ This directory and its sub-directories are for the ALSA
+ sequencer. This directory contains the sequencer core and
+ primary sequencer modules such like snd-seq-midi,
+ snd-seq-virmidi, etc. They are compiled only when
+ <constant>CONFIG_SND_SEQUENCER</constant> is set in the kernel
+ config.
+ </para>
+ </section>
+
+ <section id="file-tree-core-directory-seq-oss">
+ <title>core/seq/oss</title>
+ <para>
+ This contains the OSS sequencer emulation codes.
+ </para>
+ </section>
+
+ <section id="file-tree-core-directory-deq-instr">
+ <title>core/seq/instr</title>
+ <para>
+ This directory contains the modules for the sequencer
+ instrument layer.
+ </para>
+ </section>
+ </section>
+
+ <section id="file-tree-include-directory">
+ <title>include directory</title>
+ <para>
+ This is the place for the public header files of ALSA drivers,
+ which are to be exported to user-space, or included by
+ several files at different directories. Basically, the private
+ header files should not be placed in this directory, but you may
+ still find files there, due to historical reasons :)
+ </para>
+ </section>
+
+ <section id="file-tree-drivers-directory">
+ <title>drivers directory</title>
+ <para>
+ This directory contains code shared among different drivers
+ on different architectures. They are hence supposed not to be
+ architecture-specific.
+ For example, the dummy pcm driver and the serial MIDI
+ driver are found in this directory. In the sub-directories,
+ there is code for components which are independent from
+ bus and cpu architectures.
+ </para>
+
+ <section id="file-tree-drivers-directory-mpu401">
+ <title>drivers/mpu401</title>
+ <para>
+ The MPU401 and MPU401-UART modules are stored here.
+ </para>
+ </section>
+
+ <section id="file-tree-drivers-directory-opl3">
+ <title>drivers/opl3 and opl4</title>
+ <para>
+ The OPL3 and OPL4 FM-synth stuff is found here.
+ </para>
+ </section>
+ </section>
+
+ <section id="file-tree-i2c-directory">
+ <title>i2c directory</title>
+ <para>
+ This contains the ALSA i2c components.
+ </para>
+
+ <para>
+ Although there is a standard i2c layer on Linux, ALSA has its
+ own i2c code for some cards, because the soundcard needs only a
+ simple operation and the standard i2c API is too complicated for
+ such a purpose.
+ </para>
+
+ <section id="file-tree-i2c-directory-l3">
+ <title>i2c/l3</title>
+ <para>
+ This is a sub-directory for ARM L3 i2c.
+ </para>
+ </section>
+ </section>
+
+ <section id="file-tree-synth-directory">
+ <title>synth directory</title>
+ <para>
+ This contains the synth middle-level modules.
+ </para>
+
+ <para>
+ So far, there is only Emu8000/Emu10k1 synth driver under
+ the <filename>synth/emux</filename> sub-directory.
+ </para>
+ </section>
+
+ <section id="file-tree-pci-directory">
+ <title>pci directory</title>
+ <para>
+ This directory and its sub-directories hold the top-level card modules
+ for PCI soundcards and the code specific to the PCI BUS.
+ </para>
+
+ <para>
+ The drivers compiled from a single file are stored directly
+ in the pci directory, while the drivers with several source files are
+ stored on their own sub-directory (e.g. emu10k1, ice1712).
+ </para>
+ </section>
+
+ <section id="file-tree-isa-directory">
+ <title>isa directory</title>
+ <para>
+ This directory and its sub-directories hold the top-level card modules
+ for ISA soundcards.
+ </para>
+ </section>
+
+ <section id="file-tree-arm-ppc-sparc-directories">
+ <title>arm, ppc, and sparc directories</title>
+ <para>
+ They are used for top-level card modules which are
+ specific to one of these architectures.
+ </para>
+ </section>
+
+ <section id="file-tree-usb-directory">
+ <title>usb directory</title>
+ <para>
+ This directory contains the USB-audio driver. In the latest version, the
+ USB MIDI driver is integrated in the usb-audio driver.
+ </para>
+ </section>
+
+ <section id="file-tree-pcmcia-directory">
+ <title>pcmcia directory</title>
+ <para>
+ The PCMCIA, especially PCCard drivers will go here. CardBus
+ drivers will be in the pci directory, because their API is identical
+ to that of standard PCI cards.
+ </para>
+ </section>
+
+ <section id="file-tree-oss-directory">
+ <title>oss directory</title>
+ <para>
+ The OSS/Lite source files are stored here in Linux 2.6 (or
+ later) tree. In the ALSA driver tarball, this directory is empty,
+ of course :)
+ </para>
+ </section>
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- Basic Flow for PCI Drivers -->
+<!-- ****************************************************** -->
+ <chapter id="basic-flow">
+ <title>Basic Flow for PCI Drivers</title>
+
+ <section id="basic-flow-outline">
+ <title>Outline</title>
+ <para>
+ The minimum flow for PCI soundcards is as follows:
+
+ <itemizedlist>
+ <listitem><para>define the PCI ID table (see the section
+ <link linkend="pci-resource-entries"><citetitle>PCI Entries
+ </citetitle></link>).</para></listitem>
+ <listitem><para>create <function>probe()</function> callback.</para></listitem>
+ <listitem><para>create <function>remove()</function> callback.</para></listitem>
+ <listitem><para>create a <structname>pci_driver</structname> structure
+ containing the three pointers above.</para></listitem>
+ <listitem><para>create an <function>init()</function> function just calling
+ the <function>pci_register_driver()</function> to register the pci_driver table
+ defined above.</para></listitem>
+ <listitem><para>create an <function>exit()</function> function to call
+ the <function>pci_unregister_driver()</function> function.</para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="basic-flow-example">
+ <title>Full Code Example</title>
+ <para>
+ The code example is shown below. Some parts are kept
+ unimplemented at this moment but will be filled in the
+ next sections. The numbers in the comment lines of the
+ <function>snd_mychip_probe()</function> function
+ refer to details explained in the following section.
+
+ <example>
+ <title>Basic Flow for PCI Drivers - Example</title>
+ <programlisting>
+<![CDATA[
+ #include <linux/init.h>
+ #include <linux/pci.h>
+ #include <linux/slab.h>
+ #include <sound/core.h>
+ #include <sound/initval.h>
+
+ /* module parameters (see "Module Parameters") */
+ /* SNDRV_CARDS: maximum number of cards supported by this module */
+ static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
+ static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
+ static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
+
+ /* definition of the chip-specific record */
+ struct mychip {
+ struct snd_card *card;
+ /* the rest of the implementation will be in section
+ * "PCI Resource Management"
+ */
+ };
+
+ /* chip-specific destructor
+ * (see "PCI Resource Management")
+ */
+ static int snd_mychip_free(struct mychip *chip)
+ {
+ .... /* will be implemented later... */
+ }
+
+ /* component-destructor
+ * (see "Management of Cards and Components")
+ */
+ static int snd_mychip_dev_free(struct snd_device *device)
+ {
+ return snd_mychip_free(device->device_data);
+ }
+
+ /* chip-specific constructor
+ * (see "Management of Cards and Components")
+ */
+ static int __devinit snd_mychip_create(struct snd_card *card,
+ struct pci_dev *pci,
+ struct mychip **rchip)
+ {
+ struct mychip *chip;
+ int err;
+ static struct snd_device_ops ops = {
+ .dev_free = snd_mychip_dev_free,
+ };
+
+ *rchip = NULL;
+
+ /* check PCI availability here
+ * (see "PCI Resource Management")
+ */
+ ....
+
+ /* allocate a chip-specific data with zero filled */
+ chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ if (chip == NULL)
+ return -ENOMEM;
+
+ chip->card = card;
+
+ /* rest of initialization here; will be implemented
+ * later, see "PCI Resource Management"
+ */
+ ....
+
+ err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
+ if (err < 0) {
+ snd_mychip_free(chip);
+ return err;
+ }
+
+ snd_card_set_dev(card, &pci->dev);
+
+ *rchip = chip;
+ return 0;
+ }
+
+ /* constructor -- see "Constructor" sub-section */
+ static int __devinit snd_mychip_probe(struct pci_dev *pci,
+ const struct pci_device_id *pci_id)
+ {
+ static int dev;
+ struct snd_card *card;
+ struct mychip *chip;
+ int err;
+
+ /* (1) */
+ if (dev >= SNDRV_CARDS)
+ return -ENODEV;
+ if (!enable[dev]) {
+ dev++;
+ return -ENOENT;
+ }
+
+ /* (2) */
+ card = snd_card_new(index[dev], id[dev], THIS_MODULE, 0);
+ if (card == NULL)
+ return -ENOMEM;
+
+ /* (3) */
+ err = snd_mychip_create(card, pci, &chip);
+ if (err < 0) {
+ snd_card_free(card);
+ return err;
+ }
+
+ /* (4) */
+ strcpy(card->driver, "My Chip");
+ strcpy(card->shortname, "My Own Chip 123");
+ sprintf(card->longname, "%s at 0x%lx irq %i",
+ card->shortname, chip->ioport, chip->irq);
+
+ /* (5) */
+ .... /* implemented later */
+
+ /* (6) */
+ err = snd_card_register(card);
+ if (err < 0) {
+ snd_card_free(card);
+ return err;
+ }
+
+ /* (7) */
+ pci_set_drvdata(pci, card);
+ dev++;
+ return 0;
+ }
+
+ /* destructor -- see the "Destructor" sub-section */
+ static void __devexit snd_mychip_remove(struct pci_dev *pci)
+ {
+ snd_card_free(pci_get_drvdata(pci));
+ pci_set_drvdata(pci, NULL);
+ }
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </section>
+
+ <section id="basic-flow-constructor">
+ <title>Constructor</title>
+ <para>
+ The real constructor of PCI drivers is the <function>probe</function> callback.
+ The <function>probe</function> callback and other component-constructors which are called
+ from the <function>probe</function> callback should be defined with
+ the <parameter>__devinit</parameter> prefix. You
+ cannot use the <parameter>__init</parameter> prefix for them,
+ because any PCI device could be a hotplug device.
+ </para>
+
+ <para>
+ In the <function>probe</function> callback, the following scheme is often used.
+ </para>
+
+ <section id="basic-flow-constructor-device-index">
+ <title>1) Check and increment the device index.</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int dev;
+ ....
+ if (dev >= SNDRV_CARDS)
+ return -ENODEV;
+ if (!enable[dev]) {
+ dev++;
+ return -ENOENT;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+
+ where enable[dev] is the module option.
+ </para>
+
+ <para>
+ Each time the <function>probe</function> callback is called, check the
+ availability of the device. If not available, simply increment
+ the device index and returns. dev will be incremented also
+ later (<link
+ linkend="basic-flow-constructor-set-pci"><citetitle>step
+ 7</citetitle></link>).
+ </para>
+ </section>
+
+ <section id="basic-flow-constructor-create-card">
+ <title>2) Create a card instance</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_card *card;
+ ....
+ card = snd_card_new(index[dev], id[dev], THIS_MODULE, 0);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The details will be explained in the section
+ <link linkend="card-management-card-instance"><citetitle>
+ Management of Cards and Components</citetitle></link>.
+ </para>
+ </section>
+
+ <section id="basic-flow-constructor-create-main">
+ <title>3) Create a main component</title>
+ <para>
+ In this part, the PCI resources are allocated.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct mychip *chip;
+ ....
+ err = snd_mychip_create(card, pci, &chip);
+ if (err < 0) {
+ snd_card_free(card);
+ return err;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+
+ The details will be explained in the section <link
+ linkend="pci-resource"><citetitle>PCI Resource
+ Management</citetitle></link>.
+ </para>
+ </section>
+
+ <section id="basic-flow-constructor-main-component">
+ <title>4) Set the driver ID and name strings.</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ strcpy(card->driver, "My Chip");
+ strcpy(card->shortname, "My Own Chip 123");
+ sprintf(card->longname, "%s at 0x%lx irq %i",
+ card->shortname, chip->ioport, chip->irq);
+]]>
+ </programlisting>
+ </informalexample>
+
+ The driver field holds the minimal ID string of the
+ chip. This is used by alsa-lib's configurator, so keep it
+ simple but unique.
+ Even the same driver can have different driver IDs to
+ distinguish the functionality of each chip type.
+ </para>
+
+ <para>
+ The shortname field is a string shown as more verbose
+ name. The longname field contains the information
+ shown in <filename>/proc/asound/cards</filename>.
+ </para>
+ </section>
+
+ <section id="basic-flow-constructor-create-other">
+ <title>5) Create other components, such as mixer, MIDI, etc.</title>
+ <para>
+ Here you define the basic components such as
+ <link linkend="pcm-interface"><citetitle>PCM</citetitle></link>,
+ mixer (e.g. <link linkend="api-ac97"><citetitle>AC97</citetitle></link>),
+ MIDI (e.g. <link linkend="midi-interface"><citetitle>MPU-401</citetitle></link>),
+ and other interfaces.
+ Also, if you want a <link linkend="proc-interface"><citetitle>proc
+ file</citetitle></link>, define it here, too.
+ </para>
+ </section>
+
+ <section id="basic-flow-constructor-register-card">
+ <title>6) Register the card instance.</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ err = snd_card_register(card);
+ if (err < 0) {
+ snd_card_free(card);
+ return err;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Will be explained in the section <link
+ linkend="card-management-registration"><citetitle>Management
+ of Cards and Components</citetitle></link>, too.
+ </para>
+ </section>
+
+ <section id="basic-flow-constructor-set-pci">
+ <title>7) Set the PCI driver data and return zero.</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ pci_set_drvdata(pci, card);
+ dev++;
+ return 0;
+]]>
+ </programlisting>
+ </informalexample>
+
+ In the above, the card record is stored. This pointer is
+ used in the remove callback and power-management
+ callbacks, too.
+ </para>
+ </section>
+ </section>
+
+ <section id="basic-flow-destructor">
+ <title>Destructor</title>
+ <para>
+ The destructor, remove callback, simply releases the card
+ instance. Then the ALSA middle layer will release all the
+ attached components automatically.
+ </para>
+
+ <para>
+ It would be typically like the following:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static void __devexit snd_mychip_remove(struct pci_dev *pci)
+ {
+ snd_card_free(pci_get_drvdata(pci));
+ pci_set_drvdata(pci, NULL);
+ }
+]]>
+ </programlisting>
+ </informalexample>
+
+ The above code assumes that the card pointer is set to the PCI
+ driver data.
+ </para>
+ </section>
+
+ <section id="basic-flow-header-files">
+ <title>Header Files</title>
+ <para>
+ For the above example, at least the following include files
+ are necessary.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ #include <linux/init.h>
+ #include <linux/pci.h>
+ #include <linux/slab.h>
+ #include <sound/core.h>
+ #include <sound/initval.h>
+]]>
+ </programlisting>
+ </informalexample>
+
+ where the last one is necessary only when module options are
+ defined in the source file. If the code is split into several
+ files, the files without module options don't need them.
+ </para>
+
+ <para>
+ In addition to these headers, you'll need
+ <filename>&lt;linux/interrupt.h&gt;</filename> for interrupt
+ handling, and <filename>&lt;asm/io.h&gt;</filename> for I/O
+ access. If you use the <function>mdelay()</function> or
+ <function>udelay()</function> functions, you'll need to include
+ <filename>&lt;linux/delay.h&gt;</filename> too.
+ </para>
+
+ <para>
+ The ALSA interfaces like the PCM and control APIs are defined in other
+ <filename>&lt;sound/xxx.h&gt;</filename> header files.
+ They have to be included after
+ <filename>&lt;sound/core.h&gt;</filename>.
+ </para>
+
+ </section>
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- Management of Cards and Components -->
+<!-- ****************************************************** -->
+ <chapter id="card-management">
+ <title>Management of Cards and Components</title>
+
+ <section id="card-management-card-instance">
+ <title>Card Instance</title>
+ <para>
+ For each soundcard, a <quote>card</quote> record must be allocated.
+ </para>
+
+ <para>
+ A card record is the headquarters of the soundcard. It manages
+ the whole list of devices (components) on the soundcard, such as
+ PCM, mixers, MIDI, synthesizer, and so on. Also, the card
+ record holds the ID and the name strings of the card, manages
+ the root of proc files, and controls the power-management states
+ and hotplug disconnections. The component list on the card
+ record is used to manage the correct release of resources at
+ destruction.
+ </para>
+
+ <para>
+ As mentioned above, to create a card instance, call
+ <function>snd_card_new()</function>.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_card *card;
+ card = snd_card_new(index, id, module, extra_size);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The function takes four arguments, the card-index number, the
+ id string, the module pointer (usually
+ <constant>THIS_MODULE</constant>),
+ and the size of extra-data space. The last argument is used to
+ allocate card-&gt;private_data for the
+ chip-specific data. Note that these data
+ are allocated by <function>snd_card_new()</function>.
+ </para>
+ </section>
+
+ <section id="card-management-component">
+ <title>Components</title>
+ <para>
+ After the card is created, you can attach the components
+ (devices) to the card instance. In an ALSA driver, a component is
+ represented as a struct <structname>snd_device</structname> object.
+ A component can be a PCM instance, a control interface, a raw
+ MIDI interface, etc. Each such instance has one component
+ entry.
+ </para>
+
+ <para>
+ A component can be created via
+ <function>snd_device_new()</function> function.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ This takes the card pointer, the device-level
+ (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the
+ callback pointers (<parameter>&amp;ops</parameter>). The
+ device-level defines the type of components and the order of
+ registration and de-registration. For most components, the
+ device-level is already defined. For a user-defined component,
+ you can use <constant>SNDRV_DEV_LOWLEVEL</constant>.
+ </para>
+
+ <para>
+ This function itself doesn't allocate the data space. The data
+ must be allocated manually beforehand, and its pointer is passed
+ as the argument. This pointer is used as the
+ (<parameter>chip</parameter> identifier in the above example)
+ for the instance.
+ </para>
+
+ <para>
+ Each pre-defined ALSA component such as ac97 and pcm calls
+ <function>snd_device_new()</function> inside its
+ constructor. The destructor for each component is defined in the
+ callback pointers. Hence, you don't need to take care of
+ calling a destructor for such a component.
+ </para>
+
+ <para>
+ If you wish to create your own component, you need to
+ set the destructor function to the dev_free callback in
+ the <parameter>ops</parameter>, so that it can be released
+ automatically via <function>snd_card_free()</function>.
+ The next example will show an implementation of chip-specific
+ data.
+ </para>
+ </section>
+
+ <section id="card-management-chip-specific">
+ <title>Chip-Specific Data</title>
+ <para>
+ Chip-specific information, e.g. the I/O port address, its
+ resource pointer, or the irq number, is stored in the
+ chip-specific record.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct mychip {
+ ....
+ };
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ In general, there are two ways of allocating the chip record.
+ </para>
+
+ <section id="card-management-chip-specific-snd-card-new">
+ <title>1. Allocating via <function>snd_card_new()</function>.</title>
+ <para>
+ As mentioned above, you can pass the extra-data-length
+ to the 4th argument of <function>snd_card_new()</function>, i.e.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ card = snd_card_new(index[dev], id[dev], THIS_MODULE, sizeof(struct mychip));
+]]>
+ </programlisting>
+ </informalexample>
+
+ struct <structname>mychip</structname> is the type of the chip record.
+ </para>
+
+ <para>
+ In return, the allocated record can be accessed as
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct mychip *chip = card->private_data;
+]]>
+ </programlisting>
+ </informalexample>
+
+ With this method, you don't have to allocate twice.
+ The record is released together with the card instance.
+ </para>
+ </section>
+
+ <section id="card-management-chip-specific-allocate-extra">
+ <title>2. Allocating an extra device.</title>
+
+ <para>
+ After allocating a card instance via
+ <function>snd_card_new()</function> (with
+ <constant>NULL</constant> on the 4th arg), call
+ <function>kzalloc()</function>.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_card *card;
+ struct mychip *chip;
+ card = snd_card_new(index[dev], id[dev], THIS_MODULE, NULL);
+ .....
+ chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The chip record should have the field to hold the card
+ pointer at least,
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct mychip {
+ struct snd_card *card;
+ ....
+ };
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Then, set the card pointer in the returned chip instance.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ chip->card = card;
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Next, initialize the fields, and register this chip
+ record as a low-level device with a specified
+ <parameter>ops</parameter>,
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static struct snd_device_ops ops = {
+ .dev_free = snd_mychip_dev_free,
+ };
+ ....
+ snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
+]]>
+ </programlisting>
+ </informalexample>
+
+ <function>snd_mychip_dev_free()</function> is the
+ device-destructor function, which will call the real
+ destructor.
+ </para>
+
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_mychip_dev_free(struct snd_device *device)
+ {
+ return snd_mychip_free(device->device_data);
+ }
+]]>
+ </programlisting>
+ </informalexample>
+
+ where <function>snd_mychip_free()</function> is the real destructor.
+ </para>
+ </section>
+ </section>
+
+ <section id="card-management-registration">
+ <title>Registration and Release</title>
+ <para>
+ After all components are assigned, register the card instance
+ by calling <function>snd_card_register()</function>. Access
+ to the device files is enabled at this point. That is, before
+ <function>snd_card_register()</function> is called, the
+ components are safely inaccessible from external side. If this
+ call fails, exit the probe function after releasing the card via
+ <function>snd_card_free()</function>.
+ </para>
+
+ <para>
+ For releasing the card instance, you can call simply
+ <function>snd_card_free()</function>. As mentioned earlier, all
+ components are released automatically by this call.
+ </para>
+
+ <para>
+ As further notes, the destructors (both
+ <function>snd_mychip_dev_free</function> and
+ <function>snd_mychip_free</function>) cannot be defined with
+ the <parameter>__devexit</parameter> prefix, because they may be
+ called from the constructor, too, at the false path.
+ </para>
+
+ <para>
+ For a device which allows hotplugging, you can use
+ <function>snd_card_free_when_closed</function>. This one will
+ postpone the destruction until all devices are closed.
+ </para>
+
+ </section>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- PCI Resource Management -->
+<!-- ****************************************************** -->
+ <chapter id="pci-resource">
+ <title>PCI Resource Management</title>
+
+ <section id="pci-resource-example">
+ <title>Full Code Example</title>
+ <para>
+ In this section, we'll complete the chip-specific constructor,
+ destructor and PCI entries. Example code is shown first,
+ below.
+
+ <example>
+ <title>PCI Resource Management Example</title>
+ <programlisting>
+<![CDATA[
+ struct mychip {
+ struct snd_card *card;
+ struct pci_dev *pci;
+
+ unsigned long port;
+ int irq;
+ };
+
+ static int snd_mychip_free(struct mychip *chip)
+ {
+ /* disable hardware here if any */
+ .... /* (not implemented in this document) */
+
+ /* release the irq */
+ if (chip->irq >= 0)
+ free_irq(chip->irq, chip);
+ /* release the I/O ports & memory */
+ pci_release_regions(chip->pci);
+ /* disable the PCI entry */
+ pci_disable_device(chip->pci);
+ /* release the data */
+ kfree(chip);
+ return 0;
+ }
+
+ /* chip-specific constructor */
+ static int __devinit snd_mychip_create(struct snd_card *card,
+ struct pci_dev *pci,
+ struct mychip **rchip)
+ {
+ struct mychip *chip;
+ int err;
+ static struct snd_device_ops ops = {
+ .dev_free = snd_mychip_dev_free,
+ };
+
+ *rchip = NULL;
+
+ /* initialize the PCI entry */
+ err = pci_enable_device(pci);
+ if (err < 0)
+ return err;
+ /* check PCI availability (28bit DMA) */
+ if (pci_set_dma_mask(pci, DMA_28BIT_MASK) < 0 ||
+ pci_set_consistent_dma_mask(pci, DMA_28BIT_MASK) < 0) {
+ printk(KERN_ERR "error to set 28bit mask DMA\n");
+ pci_disable_device(pci);
+ return -ENXIO;
+ }
+
+ chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ if (chip == NULL) {
+ pci_disable_device(pci);
+ return -ENOMEM;
+ }
+
+ /* initialize the stuff */
+ chip->card = card;
+ chip->pci = pci;
+ chip->irq = -1;
+
+ /* (1) PCI resource allocation */
+ err = pci_request_regions(pci, "My Chip");
+ if (err < 0) {
+ kfree(chip);
+ pci_disable_device(pci);
+ return err;
+ }
+ chip->port = pci_resource_start(pci, 0);
+ if (request_irq(pci->irq, snd_mychip_interrupt,
+ IRQF_SHARED, "My Chip", chip)) {
+ printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
+ snd_mychip_free(chip);
+ return -EBUSY;
+ }
+ chip->irq = pci->irq;
+
+ /* (2) initialization of the chip hardware */
+ .... /* (not implemented in this document) */
+
+ err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
+ if (err < 0) {
+ snd_mychip_free(chip);
+ return err;
+ }
+
+ snd_card_set_dev(card, &pci->dev);
+
+ *rchip = chip;
+ return 0;
+ }
+
+ /* PCI IDs */
+ static struct pci_device_id snd_mychip_ids[] = {
+ { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
+ PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
+ ....
+ { 0, }
+ };
+ MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
+
+ /* pci_driver definition */
+ static struct pci_driver driver = {
+ .name = "My Own Chip",
+ .id_table = snd_mychip_ids,
+ .probe = snd_mychip_probe,
+ .remove = __devexit_p(snd_mychip_remove),
+ };
+
+ /* module initialization */
+ static int __init alsa_card_mychip_init(void)
+ {
+ return pci_register_driver(&driver);
+ }
+
+ /* module clean up */
+ static void __exit alsa_card_mychip_exit(void)
+ {
+ pci_unregister_driver(&driver);
+ }
+
+ module_init(alsa_card_mychip_init)
+ module_exit(alsa_card_mychip_exit)
+
+ EXPORT_NO_SYMBOLS; /* for old kernels only */
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </section>
+
+ <section id="pci-resource-some-haftas">
+ <title>Some Hafta's</title>
+ <para>
+ The allocation of PCI resources is done in the
+ <function>probe()</function> function, and usually an extra
+ <function>xxx_create()</function> function is written for this
+ purpose.
+ </para>
+
+ <para>
+ In the case of PCI devices, you first have to call
+ the <function>pci_enable_device()</function> function before
+ allocating resources. Also, you need to set the proper PCI DMA
+ mask to limit the accessed I/O range. In some cases, you might
+ need to call <function>pci_set_master()</function> function,
+ too.
+ </para>
+
+ <para>
+ Suppose the 28bit mask, and the code to be added would be like:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ err = pci_enable_device(pci);
+ if (err < 0)
+ return err;
+ if (pci_set_dma_mask(pci, DMA_28BIT_MASK) < 0 ||
+ pci_set_consistent_dma_mask(pci, DMA_28BIT_MASK) < 0) {
+ printk(KERN_ERR "error to set 28bit mask DMA\n");
+ pci_disable_device(pci);
+ return -ENXIO;
+ }
+
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+ </section>
+
+ <section id="pci-resource-resource-allocation">
+ <title>Resource Allocation</title>
+ <para>
+ The allocation of I/O ports and irqs is done via standard kernel
+ functions. Unlike ALSA ver.0.5.x., there are no helpers for
+ that. And these resources must be released in the destructor
+ function (see below). Also, on ALSA 0.9.x, you don't need to
+ allocate (pseudo-)DMA for PCI like in ALSA 0.5.x.
+ </para>
+
+ <para>
+ Now assume that the PCI device has an I/O port with 8 bytes
+ and an interrupt. Then struct <structname>mychip</structname> will have the
+ following fields:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct mychip {
+ struct snd_card *card;
+
+ unsigned long port;
+ int irq;
+ };
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ For an I/O port (and also a memory region), you need to have
+ the resource pointer for the standard resource management. For
+ an irq, you have to keep only the irq number (integer). But you
+ need to initialize this number as -1 before actual allocation,
+ since irq 0 is valid. The port address and its resource pointer
+ can be initialized as null by
+ <function>kzalloc()</function> automatically, so you
+ don't have to take care of resetting them.
+ </para>
+
+ <para>
+ The allocation of an I/O port is done like this:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ err = pci_request_regions(pci, "My Chip");
+ if (err < 0) {
+ kfree(chip);
+ pci_disable_device(pci);
+ return err;
+ }
+ chip->port = pci_resource_start(pci, 0);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ <!-- obsolete -->
+ It will reserve the I/O port region of 8 bytes of the given
+ PCI device. The returned value, chip-&gt;res_port, is allocated
+ via <function>kmalloc()</function> by
+ <function>request_region()</function>. The pointer must be
+ released via <function>kfree()</function>, but there is a
+ problem with this. This issue will be explained later.
+ </para>
+
+ <para>
+ The allocation of an interrupt source is done like this:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ if (request_irq(pci->irq, snd_mychip_interrupt,
+ IRQF_SHARED, "My Chip", chip)) {
+ printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
+ snd_mychip_free(chip);
+ return -EBUSY;
+ }
+ chip->irq = pci->irq;
+]]>
+ </programlisting>
+ </informalexample>
+
+ where <function>snd_mychip_interrupt()</function> is the
+ interrupt handler defined <link
+ linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>.
+ Note that chip-&gt;irq should be defined
+ only when <function>request_irq()</function> succeeded.
+ </para>
+
+ <para>
+ On the PCI bus, interrupts can be shared. Thus,
+ <constant>IRQF_SHARED</constant> is used as the interrupt flag of
+ <function>request_irq()</function>.
+ </para>
+
+ <para>
+ The last argument of <function>request_irq()</function> is the
+ data pointer passed to the interrupt handler. Usually, the
+ chip-specific record is used for that, but you can use what you
+ like, too.
+ </para>
+
+ <para>
+ I won't give details about the interrupt handler at this
+ point, but at least its appearance can be explained now. The
+ interrupt handler looks usually like the following:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
+ {
+ struct mychip *chip = dev_id;
+ ....
+ return IRQ_HANDLED;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Now let's write the corresponding destructor for the resources
+ above. The role of destructor is simple: disable the hardware
+ (if already activated) and release the resources. So far, we
+ have no hardware part, so the disabling code is not written here.
+ </para>
+
+ <para>
+ To release the resources, the <quote>check-and-release</quote>
+ method is a safer way. For the interrupt, do like this:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ if (chip->irq >= 0)
+ free_irq(chip->irq, chip);
+]]>
+ </programlisting>
+ </informalexample>
+
+ Since the irq number can start from 0, you should initialize
+ chip-&gt;irq with a negative value (e.g. -1), so that you can
+ check the validity of the irq number as above.
+ </para>
+
+ <para>
+ When you requested I/O ports or memory regions via
+ <function>pci_request_region()</function> or
+ <function>pci_request_regions()</function> like in this example,
+ release the resource(s) using the corresponding function,
+ <function>pci_release_region()</function> or
+ <function>pci_release_regions()</function>.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ pci_release_regions(chip->pci);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ When you requested manually via <function>request_region()</function>
+ or <function>request_mem_region</function>, you can release it via
+ <function>release_resource()</function>. Suppose that you keep
+ the resource pointer returned from <function>request_region()</function>
+ in chip-&gt;res_port, the release procedure looks like:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ release_and_free_resource(chip->res_port);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Don't forget to call <function>pci_disable_device()</function>
+ before the end.
+ </para>
+
+ <para>
+ And finally, release the chip-specific record.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ kfree(chip);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Again, remember that you cannot
+ use the <parameter>__devexit</parameter> prefix for this destructor.
+ </para>
+
+ <para>
+ We didn't implement the hardware disabling part in the above.
+ If you need to do this, please note that the destructor may be
+ called even before the initialization of the chip is completed.
+ It would be better to have a flag to skip hardware disabling
+ if the hardware was not initialized yet.
+ </para>
+
+ <para>
+ When the chip-data is assigned to the card using
+ <function>snd_device_new()</function> with
+ <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is
+ called at the last. That is, it is assured that all other
+ components like PCMs and controls have already been released.
+ You don't have to stop PCMs, etc. explicitly, but just
+ call low-level hardware stopping.
+ </para>
+
+ <para>
+ The management of a memory-mapped region is almost as same as
+ the management of an I/O port. You'll need three fields like
+ the following:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct mychip {
+ ....
+ unsigned long iobase_phys;
+ void __iomem *iobase_virt;
+ };
+]]>
+ </programlisting>
+ </informalexample>
+
+ and the allocation would be like below:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ if ((err = pci_request_regions(pci, "My Chip")) < 0) {
+ kfree(chip);
+ return err;
+ }
+ chip->iobase_phys = pci_resource_start(pci, 0);
+ chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
+ pci_resource_len(pci, 0));
+]]>
+ </programlisting>
+ </informalexample>
+
+ and the corresponding destructor would be:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_mychip_free(struct mychip *chip)
+ {
+ ....
+ if (chip->iobase_virt)
+ iounmap(chip->iobase_virt);
+ ....
+ pci_release_regions(chip->pci);
+ ....
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ </section>
+
+ <section id="pci-resource-device-struct">
+ <title>Registration of Device Struct</title>
+ <para>
+ At some point, typically after calling <function>snd_device_new()</function>,
+ you need to register the struct <structname>device</structname> of the chip
+ you're handling for udev and co. ALSA provides a macro for compatibility with
+ older kernels. Simply call like the following:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_card_set_dev(card, &pci->dev);
+]]>
+ </programlisting>
+ </informalexample>
+ so that it stores the PCI's device pointer to the card. This will be
+ referred by ALSA core functions later when the devices are registered.
+ </para>
+ <para>
+ In the case of non-PCI, pass the proper device struct pointer of the BUS
+ instead. (In the case of legacy ISA without PnP, you don't have to do
+ anything.)
+ </para>
+ </section>
+
+ <section id="pci-resource-entries">
+ <title>PCI Entries</title>
+ <para>
+ So far, so good. Let's finish the missing PCI
+ stuff. At first, we need a
+ <structname>pci_device_id</structname> table for this
+ chipset. It's a table of PCI vendor/device ID number, and some
+ masks.
+ </para>
+
+ <para>
+ For example,
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static struct pci_device_id snd_mychip_ids[] = {
+ { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
+ PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
+ ....
+ { 0, }
+ };
+ MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The first and second fields of
+ the <structname>pci_device_id</structname> structure are the vendor and
+ device IDs. If you have no reason to filter the matching
+ devices, you can leave the remaining fields as above. The last
+ field of the <structname>pci_device_id</structname> struct contains
+ private data for this entry. You can specify any value here, for
+ example, to define specific operations for supported device IDs.
+ Such an example is found in the intel8x0 driver.
+ </para>
+
+ <para>
+ The last entry of this list is the terminator. You must
+ specify this all-zero entry.
+ </para>
+
+ <para>
+ Then, prepare the <structname>pci_driver</structname> record:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static struct pci_driver driver = {
+ .name = "My Own Chip",
+ .id_table = snd_mychip_ids,
+ .probe = snd_mychip_probe,
+ .remove = __devexit_p(snd_mychip_remove),
+ };
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The <structfield>probe</structfield> and
+ <structfield>remove</structfield> functions have already
+ been defined in the previous sections.
+ The <structfield>remove</structfield> function should
+ be defined with the
+ <function>__devexit_p()</function> macro, so that it's not
+ defined for built-in (and non-hot-pluggable) case. The
+ <structfield>name</structfield>
+ field is the name string of this device. Note that you must not
+ use a slash <quote>/</quote> in this string.
+ </para>
+
+ <para>
+ And at last, the module entries:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int __init alsa_card_mychip_init(void)
+ {
+ return pci_register_driver(&driver);
+ }
+
+ static void __exit alsa_card_mychip_exit(void)
+ {
+ pci_unregister_driver(&driver);
+ }
+
+ module_init(alsa_card_mychip_init)
+ module_exit(alsa_card_mychip_exit)
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Note that these module entries are tagged with
+ <parameter>__init</parameter> and
+ <parameter>__exit</parameter> prefixes, not
+ <parameter>__devinit</parameter> nor
+ <parameter>__devexit</parameter>.
+ </para>
+
+ <para>
+ Oh, one thing was forgotten. If you have no exported symbols,
+ you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ EXPORT_NO_SYMBOLS;
+]]>
+ </programlisting>
+ </informalexample>
+
+ That's all!
+ </para>
+ </section>
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- PCM Interface -->
+<!-- ****************************************************** -->
+ <chapter id="pcm-interface">
+ <title>PCM Interface</title>
+
+ <section id="pcm-interface-general">
+ <title>General</title>
+ <para>
+ The PCM middle layer of ALSA is quite powerful and it is only
+ necessary for each driver to implement the low-level functions
+ to access its hardware.
+ </para>
+
+ <para>
+ For accessing to the PCM layer, you need to include
+ <filename>&lt;sound/pcm.h&gt;</filename> first. In addition,
+ <filename>&lt;sound/pcm_params.h&gt;</filename> might be needed
+ if you access to some functions related with hw_param.
+ </para>
+
+ <para>
+ Each card device can have up to four pcm instances. A pcm
+ instance corresponds to a pcm device file. The limitation of
+ number of instances comes only from the available bit size of
+ the Linux's device numbers. Once when 64bit device number is
+ used, we'll have more pcm instances available.
+ </para>
+
+ <para>
+ A pcm instance consists of pcm playback and capture streams,
+ and each pcm stream consists of one or more pcm substreams. Some
+ soundcards support multiple playback functions. For example,
+ emu10k1 has a PCM playback of 32 stereo substreams. In this case, at
+ each open, a free substream is (usually) automatically chosen
+ and opened. Meanwhile, when only one substream exists and it was
+ already opened, the successful open will either block
+ or error with <constant>EAGAIN</constant> according to the
+ file open mode. But you don't have to care about such details in your
+ driver. The PCM middle layer will take care of such work.
+ </para>
+ </section>
+
+ <section id="pcm-interface-example">
+ <title>Full Code Example</title>
+ <para>
+ The example code below does not include any hardware access
+ routines but shows only the skeleton, how to build up the PCM
+ interfaces.
+
+ <example>
+ <title>PCM Example Code</title>
+ <programlisting>
+<![CDATA[
+ #include <sound/pcm.h>
+ ....
+
+ /* hardware definition */
+ static struct snd_pcm_hardware snd_mychip_playback_hw = {
+ .info = (SNDRV_PCM_INFO_MMAP |
+ SNDRV_PCM_INFO_INTERLEAVED |
+ SNDRV_PCM_INFO_BLOCK_TRANSFER |
+ SNDRV_PCM_INFO_MMAP_VALID),
+ .formats = SNDRV_PCM_FMTBIT_S16_LE,
+ .rates = SNDRV_PCM_RATE_8000_48000,
+ .rate_min = 8000,
+ .rate_max = 48000,
+ .channels_min = 2,
+ .channels_max = 2,
+ .buffer_bytes_max = 32768,
+ .period_bytes_min = 4096,
+ .period_bytes_max = 32768,
+ .periods_min = 1,
+ .periods_max = 1024,
+ };
+
+ /* hardware definition */
+ static struct snd_pcm_hardware snd_mychip_capture_hw = {
+ .info = (SNDRV_PCM_INFO_MMAP |
+ SNDRV_PCM_INFO_INTERLEAVED |
+ SNDRV_PCM_INFO_BLOCK_TRANSFER |
+ SNDRV_PCM_INFO_MMAP_VALID),
+ .formats = SNDRV_PCM_FMTBIT_S16_LE,
+ .rates = SNDRV_PCM_RATE_8000_48000,
+ .rate_min = 8000,
+ .rate_max = 48000,
+ .channels_min = 2,
+ .channels_max = 2,
+ .buffer_bytes_max = 32768,
+ .period_bytes_min = 4096,
+ .period_bytes_max = 32768,
+ .periods_min = 1,
+ .periods_max = 1024,
+ };
+
+ /* open callback */
+ static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
+ {
+ struct mychip *chip = snd_pcm_substream_chip(substream);
+ struct snd_pcm_runtime *runtime = substream->runtime;
+
+ runtime->hw = snd_mychip_playback_hw;
+ /* more hardware-initialization will be done here */
+ ....
+ return 0;
+ }
+
+ /* close callback */
+ static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
+ {
+ struct mychip *chip = snd_pcm_substream_chip(substream);
+ /* the hardware-specific codes will be here */
+ ....
+ return 0;
+
+ }
+
+ /* open callback */
+ static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
+ {
+ struct mychip *chip = snd_pcm_substream_chip(substream);
+ struct snd_pcm_runtime *runtime = substream->runtime;
+
+ runtime->hw = snd_mychip_capture_hw;
+ /* more hardware-initialization will be done here */
+ ....
+ return 0;
+ }
+
+ /* close callback */
+ static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
+ {
+ struct mychip *chip = snd_pcm_substream_chip(substream);
+ /* the hardware-specific codes will be here */
+ ....
+ return 0;
+
+ }
+
+ /* hw_params callback */
+ static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
+ struct snd_pcm_hw_params *hw_params)
+ {
+ return snd_pcm_lib_malloc_pages(substream,
+ params_buffer_bytes(hw_params));
+ }
+
+ /* hw_free callback */
+ static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
+ {
+ return snd_pcm_lib_free_pages(substream);
+ }
+
+ /* prepare callback */
+ static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
+ {
+ struct mychip *chip = snd_pcm_substream_chip(substream);
+ struct snd_pcm_runtime *runtime = substream->runtime;
+
+ /* set up the hardware with the current configuration
+ * for example...
+ */
+ mychip_set_sample_format(chip, runtime->format);
+ mychip_set_sample_rate(chip, runtime->rate);
+ mychip_set_channels(chip, runtime->channels);
+ mychip_set_dma_setup(chip, runtime->dma_addr,
+ chip->buffer_size,
+ chip->period_size);
+ return 0;
+ }
+
+ /* trigger callback */
+ static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
+ int cmd)
+ {
+ switch (cmd) {
+ case SNDRV_PCM_TRIGGER_START:
+ /* do something to start the PCM engine */
+ ....
+ break;
+ case SNDRV_PCM_TRIGGER_STOP:
+ /* do something to stop the PCM engine */
+ ....
+ break;
+ default:
+ return -EINVAL;
+ }
+ }
+
+ /* pointer callback */
+ static snd_pcm_uframes_t
+ snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
+ {
+ struct mychip *chip = snd_pcm_substream_chip(substream);
+ unsigned int current_ptr;
+
+ /* get the current hardware pointer */
+ current_ptr = mychip_get_hw_pointer(chip);
+ return current_ptr;
+ }
+
+ /* operators */
+ static struct snd_pcm_ops snd_mychip_playback_ops = {
+ .open = snd_mychip_playback_open,
+ .close = snd_mychip_playback_close,
+ .ioctl = snd_pcm_lib_ioctl,
+ .hw_params = snd_mychip_pcm_hw_params,
+ .hw_free = snd_mychip_pcm_hw_free,
+ .prepare = snd_mychip_pcm_prepare,
+ .trigger = snd_mychip_pcm_trigger,
+ .pointer = snd_mychip_pcm_pointer,
+ };
+
+ /* operators */
+ static struct snd_pcm_ops snd_mychip_capture_ops = {
+ .open = snd_mychip_capture_open,
+ .close = snd_mychip_capture_close,
+ .ioctl = snd_pcm_lib_ioctl,
+ .hw_params = snd_mychip_pcm_hw_params,
+ .hw_free = snd_mychip_pcm_hw_free,
+ .prepare = snd_mychip_pcm_prepare,
+ .trigger = snd_mychip_pcm_trigger,
+ .pointer = snd_mychip_pcm_pointer,
+ };
+
+ /*
+ * definitions of capture are omitted here...
+ */
+
+ /* create a pcm device */
+ static int __devinit snd_mychip_new_pcm(struct mychip *chip)
+ {
+ struct snd_pcm *pcm;
+ int err;
+
+ err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
+ if (err < 0)
+ return err;
+ pcm->private_data = chip;
+ strcpy(pcm->name, "My Chip");
+ chip->pcm = pcm;
+ /* set operators */
+ snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
+ &snd_mychip_playback_ops);
+ snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
+ &snd_mychip_capture_ops);
+ /* pre-allocation of buffers */
+ /* NOTE: this may fail */
+ snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
+ snd_dma_pci_data(chip->pci),
+ 64*1024, 64*1024);
+ return 0;
+ }
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </section>
+
+ <section id="pcm-interface-constructor">
+ <title>Constructor</title>
+ <para>
+ A pcm instance is allocated by the <function>snd_pcm_new()</function>
+ function. It would be better to create a constructor for pcm,
+ namely,
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int __devinit snd_mychip_new_pcm(struct mychip *chip)
+ {
+ struct snd_pcm *pcm;
+ int err;
+
+ err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
+ if (err < 0)
+ return err;
+ pcm->private_data = chip;
+ strcpy(pcm->name, "My Chip");
+ chip->pcm = pcm;
+ ....
+ return 0;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The <function>snd_pcm_new()</function> function takes four
+ arguments. The first argument is the card pointer to which this
+ pcm is assigned, and the second is the ID string.
+ </para>
+
+ <para>
+ The third argument (<parameter>index</parameter>, 0 in the
+ above) is the index of this new pcm. It begins from zero. If
+ you create more than one pcm instances, specify the
+ different numbers in this argument. For example,
+ <parameter>index</parameter> = 1 for the second PCM device.
+ </para>
+
+ <para>
+ The fourth and fifth arguments are the number of substreams
+ for playback and capture, respectively. Here 1 is used for
+ both arguments. When no playback or capture substreams are available,
+ pass 0 to the corresponding argument.
+ </para>
+
+ <para>
+ If a chip supports multiple playbacks or captures, you can
+ specify more numbers, but they must be handled properly in
+ open/close, etc. callbacks. When you need to know which
+ substream you are referring to, then it can be obtained from
+ struct <structname>snd_pcm_substream</structname> data passed to each callback
+ as follows:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_pcm_substream *substream;
+ int index = substream->number;
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ After the pcm is created, you need to set operators for each
+ pcm stream.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
+ &snd_mychip_playback_ops);
+ snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
+ &snd_mychip_capture_ops);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The operators are defined typically like this:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static struct snd_pcm_ops snd_mychip_playback_ops = {
+ .open = snd_mychip_pcm_open,
+ .close = snd_mychip_pcm_close,
+ .ioctl = snd_pcm_lib_ioctl,
+ .hw_params = snd_mychip_pcm_hw_params,
+ .hw_free = snd_mychip_pcm_hw_free,
+ .prepare = snd_mychip_pcm_prepare,
+ .trigger = snd_mychip_pcm_trigger,
+ .pointer = snd_mychip_pcm_pointer,
+ };
+]]>
+ </programlisting>
+ </informalexample>
+
+ All the callbacks are described in the
+ <link linkend="pcm-interface-operators"><citetitle>
+ Operators</citetitle></link> subsection.
+ </para>
+
+ <para>
+ After setting the operators, you probably will want to
+ pre-allocate the buffer. For the pre-allocation, simply call
+ the following:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
+ snd_dma_pci_data(chip->pci),
+ 64*1024, 64*1024);
+]]>
+ </programlisting>
+ </informalexample>
+
+ It will allocate a buffer up to 64kB as default.
+ Buffer management details will be described in the later section <link
+ linkend="buffer-and-memory"><citetitle>Buffer and Memory
+ Management</citetitle></link>.
+ </para>
+
+ <para>
+ Additionally, you can set some extra information for this pcm
+ in pcm-&gt;info_flags.
+ The available values are defined as
+ <constant>SNDRV_PCM_INFO_XXX</constant> in
+ <filename>&lt;sound/asound.h&gt;</filename>, which is used for
+ the hardware definition (described later). When your soundchip
+ supports only half-duplex, specify like this:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+ </section>
+
+ <section id="pcm-interface-destructor">
+ <title>... And the Destructor?</title>
+ <para>
+ The destructor for a pcm instance is not always
+ necessary. Since the pcm device will be released by the middle
+ layer code automatically, you don't have to call the destructor
+ explicitly.
+ </para>
+
+ <para>
+ The destructor would be necessary if you created
+ special records internally and needed to release them. In such a
+ case, set the destructor function to
+ pcm-&gt;private_free:
+
+ <example>
+ <title>PCM Instance with a Destructor</title>
+ <programlisting>
+<![CDATA[
+ static void mychip_pcm_free(struct snd_pcm *pcm)
+ {
+ struct mychip *chip = snd_pcm_chip(pcm);
+ /* free your own data */
+ kfree(chip->my_private_pcm_data);
+ /* do what you like else */
+ ....
+ }
+
+ static int __devinit snd_mychip_new_pcm(struct mychip *chip)
+ {
+ struct snd_pcm *pcm;
+ ....
+ /* allocate your own data */
+ chip->my_private_pcm_data = kmalloc(...);
+ /* set the destructor */
+ pcm->private_data = chip;
+ pcm->private_free = mychip_pcm_free;
+ ....
+ }
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </section>
+
+ <section id="pcm-interface-runtime">
+ <title>Runtime Pointer - The Chest of PCM Information</title>
+ <para>
+ When the PCM substream is opened, a PCM runtime instance is
+ allocated and assigned to the substream. This pointer is
+ accessible via <constant>substream-&gt;runtime</constant>.
+ This runtime pointer holds most information you need
+ to control the PCM: the copy of hw_params and sw_params configurations, the buffer
+ pointers, mmap records, spinlocks, etc.
+ </para>
+
+ <para>
+ The definition of runtime instance is found in
+ <filename>&lt;sound/pcm.h&gt;</filename>. Here are
+ the contents of this file:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+struct _snd_pcm_runtime {
+ /* -- Status -- */
+ struct snd_pcm_substream *trigger_master;
+ snd_timestamp_t trigger_tstamp; /* trigger timestamp */
+ int overrange;
+ snd_pcm_uframes_t avail_max;
+ snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
+ snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
+
+ /* -- HW params -- */
+ snd_pcm_access_t access; /* access mode */
+ snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
+ snd_pcm_subformat_t subformat; /* subformat */
+ unsigned int rate; /* rate in Hz */
+ unsigned int channels; /* channels */
+ snd_pcm_uframes_t period_size; /* period size */
+ unsigned int periods; /* periods */
+ snd_pcm_uframes_t buffer_size; /* buffer size */
+ unsigned int tick_time; /* tick time */
+ snd_pcm_uframes_t min_align; /* Min alignment for the format */
+ size_t byte_align;
+ unsigned int frame_bits;
+ unsigned int sample_bits;
+ unsigned int info;
+ unsigned int rate_num;
+ unsigned int rate_den;
+
+ /* -- SW params -- */
+ struct timespec tstamp_mode; /* mmap timestamp is updated */
+ unsigned int period_step;
+ unsigned int sleep_min; /* min ticks to sleep */
+ snd_pcm_uframes_t start_threshold;
+ snd_pcm_uframes_t stop_threshold;
+ snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
+ noise is nearest than this */
+ snd_pcm_uframes_t silence_size; /* Silence filling size */
+ snd_pcm_uframes_t boundary; /* pointers wrap point */
+
+ snd_pcm_uframes_t silenced_start;
+ snd_pcm_uframes_t silenced_size;
+
+ snd_pcm_sync_id_t sync; /* hardware synchronization ID */
+
+ /* -- mmap -- */
+ volatile struct snd_pcm_mmap_status *status;
+ volatile struct snd_pcm_mmap_control *control;
+ atomic_t mmap_count;
+
+ /* -- locking / scheduling -- */
+ spinlock_t lock;
+ wait_queue_head_t sleep;
+ struct timer_list tick_timer;
+ struct fasync_struct *fasync;
+
+ /* -- private section -- */
+ void *private_data;
+ void (*private_free)(struct snd_pcm_runtime *runtime);
+
+ /* -- hardware description -- */
+ struct snd_pcm_hardware hw;
+ struct snd_pcm_hw_constraints hw_constraints;
+
+ /* -- interrupt callbacks -- */
+ void (*transfer_ack_begin)(struct snd_pcm_substream *substream);
+ void (*transfer_ack_end)(struct snd_pcm_substream *substream);
+
+ /* -- timer -- */
+ unsigned int timer_resolution; /* timer resolution */
+
+ /* -- DMA -- */
+ unsigned char *dma_area; /* DMA area */
+ dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
+ size_t dma_bytes; /* size of DMA area */
+
+ struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
+
+#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
+ /* -- OSS things -- */
+ struct snd_pcm_oss_runtime oss;
+#endif
+};
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ For the operators (callbacks) of each sound driver, most of
+ these records are supposed to be read-only. Only the PCM
+ middle-layer changes / updates them. The exceptions are
+ the hardware description (hw), interrupt callbacks
+ (transfer_ack_xxx), DMA buffer information, and the private
+ data. Besides, if you use the standard buffer allocation
+ method via <function>snd_pcm_lib_malloc_pages()</function>,
+ you don't need to set the DMA buffer information by yourself.
+ </para>
+
+ <para>
+ In the sections below, important records are explained.
+ </para>
+
+ <section id="pcm-interface-runtime-hw">
+ <title>Hardware Description</title>
+ <para>
+ The hardware descriptor (struct <structname>snd_pcm_hardware</structname>)
+ contains the definitions of the fundamental hardware
+ configuration. Above all, you'll need to define this in
+ <link linkend="pcm-interface-operators-open-callback"><citetitle>
+ the open callback</citetitle></link>.
+ Note that the runtime instance holds the copy of the
+ descriptor, not the pointer to the existing descriptor. That
+ is, in the open callback, you can modify the copied descriptor
+ (<constant>runtime-&gt;hw</constant>) as you need. For example, if the maximum
+ number of channels is 1 only on some chip models, you can
+ still use the same hardware descriptor and change the
+ channels_max later:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_pcm_runtime *runtime = substream->runtime;
+ ...
+ runtime->hw = snd_mychip_playback_hw; /* common definition */
+ if (chip->model == VERY_OLD_ONE)
+ runtime->hw.channels_max = 1;
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Typically, you'll have a hardware descriptor as below:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static struct snd_pcm_hardware snd_mychip_playback_hw = {
+ .info = (SNDRV_PCM_INFO_MMAP |
+ SNDRV_PCM_INFO_INTERLEAVED |
+ SNDRV_PCM_INFO_BLOCK_TRANSFER |
+ SNDRV_PCM_INFO_MMAP_VALID),
+ .formats = SNDRV_PCM_FMTBIT_S16_LE,
+ .rates = SNDRV_PCM_RATE_8000_48000,
+ .rate_min = 8000,
+ .rate_max = 48000,
+ .channels_min = 2,
+ .channels_max = 2,
+ .buffer_bytes_max = 32768,
+ .period_bytes_min = 4096,
+ .period_bytes_max = 32768,
+ .periods_min = 1,
+ .periods_max = 1024,
+ };
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem><para>
+ The <structfield>info</structfield> field contains the type and
+ capabilities of this pcm. The bit flags are defined in
+ <filename>&lt;sound/asound.h&gt;</filename> as
+ <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
+ have to specify whether the mmap is supported and which
+ interleaved format is supported.
+ When the is supported, add the
+ <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
+ hardware supports the interleaved or the non-interleaved
+ formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
+ <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
+ be set, respectively. If both are supported, you can set both,
+ too.
+ </para>
+
+ <para>
+ In the above example, <constant>MMAP_VALID</constant> and
+ <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap
+ mode. Usually both are set. Of course,
+ <constant>MMAP_VALID</constant> is set only if the mmap is
+ really supported.
+ </para>
+
+ <para>
+ The other possible flags are
+ <constant>SNDRV_PCM_INFO_PAUSE</constant> and
+ <constant>SNDRV_PCM_INFO_RESUME</constant>. The
+ <constant>PAUSE</constant> bit means that the pcm supports the
+ <quote>pause</quote> operation, while the
+ <constant>RESUME</constant> bit means that the pcm supports
+ the full <quote>suspend/resume</quote> operation.
+ If the <constant>PAUSE</constant> flag is set,
+ the <structfield>trigger</structfield> callback below
+ must handle the corresponding (pause push/release) commands.
+ The suspend/resume trigger commands can be defined even without
+ the <constant>RESUME</constant> flag. See <link
+ linkend="power-management"><citetitle>
+ Power Management</citetitle></link> section for details.
+ </para>
+
+ <para>
+ When the PCM substreams can be synchronized (typically,
+ synchronized start/stop of a playback and a capture streams),
+ you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
+ too. In this case, you'll need to check the linked-list of
+ PCM substreams in the trigger callback. This will be
+ described in the later section.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <structfield>formats</structfield> field contains the bit-flags
+ of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
+ If the hardware supports more than one format, give all or'ed
+ bits. In the example above, the signed 16bit little-endian
+ format is specified.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <structfield>rates</structfield> field contains the bit-flags of
+ supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
+ When the chip supports continuous rates, pass
+ <constant>CONTINUOUS</constant> bit additionally.
+ The pre-defined rate bits are provided only for typical
+ rates. If your chip supports unconventional rates, you need to add
+ the <constant>KNOT</constant> bit and set up the hardware
+ constraint manually (explained later).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <structfield>rate_min</structfield> and
+ <structfield>rate_max</structfield> define the minimum and
+ maximum sample rate. This should correspond somehow to
+ <structfield>rates</structfield> bits.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <structfield>channel_min</structfield> and
+ <structfield>channel_max</structfield>
+ define, as you might already expected, the minimum and maximum
+ number of channels.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <structfield>buffer_bytes_max</structfield> defines the
+ maximum buffer size in bytes. There is no
+ <structfield>buffer_bytes_min</structfield> field, since
+ it can be calculated from the minimum period size and the
+ minimum number of periods.
+ Meanwhile, <structfield>period_bytes_min</structfield> and
+ define the minimum and maximum size of the period in bytes.
+ <structfield>periods_max</structfield> and
+ <structfield>periods_min</structfield> define the maximum and
+ minimum number of periods in the buffer.
+ </para>
+
+ <para>
+ The <quote>period</quote> is a term that corresponds to
+ a fragment in the OSS world. The period defines the size at
+ which a PCM interrupt is generated. This size strongly
+ depends on the hardware.
+ Generally, the smaller period size will give you more
+ interrupts, that is, more controls.
+ In the case of capture, this size defines the input latency.
+ On the other hand, the whole buffer size defines the
+ output latency for the playback direction.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ There is also a field <structfield>fifo_size</structfield>.
+ This specifies the size of the hardware FIFO, but currently it
+ is neither used in the driver nor in the alsa-lib. So, you
+ can ignore this field.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="pcm-interface-runtime-config">
+ <title>PCM Configurations</title>
+ <para>
+ Ok, let's go back again to the PCM runtime records.
+ The most frequently referred records in the runtime instance are
+ the PCM configurations.
+ The PCM configurations are stored in the runtime instance
+ after the application sends <type>hw_params</type> data via
+ alsa-lib. There are many fields copied from hw_params and
+ sw_params structs. For example,
+ <structfield>format</structfield> holds the format type
+ chosen by the application. This field contains the enum value
+ <constant>SNDRV_PCM_FORMAT_XXX</constant>.
+ </para>
+
+ <para>
+ One thing to be noted is that the configured buffer and period
+ sizes are stored in <quote>frames</quote> in the runtime.
+ In the ALSA world, 1 frame = channels * samples-size.
+ For conversion between frames and bytes, you can use the
+ <function>frames_to_bytes()</function> and
+ <function>bytes_to_frames()</function> helper functions.
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ period_bytes = frames_to_bytes(runtime, runtime->period_size);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Also, many software parameters (sw_params) are
+ stored in frames, too. Please check the type of the field.
+ <type>snd_pcm_uframes_t</type> is for the frames as unsigned
+ integer while <type>snd_pcm_sframes_t</type> is for the frames
+ as signed integer.
+ </para>
+ </section>
+
+ <section id="pcm-interface-runtime-dma">
+ <title>DMA Buffer Information</title>
+ <para>
+ The DMA buffer is defined by the following four fields,
+ <structfield>dma_area</structfield>,
+ <structfield>dma_addr</structfield>,
+ <structfield>dma_bytes</structfield> and
+ <structfield>dma_private</structfield>.
+ The <structfield>dma_area</structfield> holds the buffer
+ pointer (the logical address). You can call
+ <function>memcpy</function> from/to
+ this pointer. Meanwhile, <structfield>dma_addr</structfield>
+ holds the physical address of the buffer. This field is
+ specified only when the buffer is a linear buffer.
+ <structfield>dma_bytes</structfield> holds the size of buffer
+ in bytes. <structfield>dma_private</structfield> is used for
+ the ALSA DMA allocator.
+ </para>
+
+ <para>
+ If you use a standard ALSA function,
+ <function>snd_pcm_lib_malloc_pages()</function>, for
+ allocating the buffer, these fields are set by the ALSA middle
+ layer, and you should <emphasis>not</emphasis> change them by
+ yourself. You can read them but not write them.
+ On the other hand, if you want to allocate the buffer by
+ yourself, you'll need to manage it in hw_params callback.
+ At least, <structfield>dma_bytes</structfield> is mandatory.
+ <structfield>dma_area</structfield> is necessary when the
+ buffer is mmapped. If your driver doesn't support mmap, this
+ field is not necessary. <structfield>dma_addr</structfield>
+ is also optional. You can use
+ <structfield>dma_private</structfield> as you like, too.
+ </para>
+ </section>
+
+ <section id="pcm-interface-runtime-status">
+ <title>Running Status</title>
+ <para>
+ The running status can be referred via <constant>runtime-&gt;status</constant>.
+ This is the pointer to the struct <structname>snd_pcm_mmap_status</structname>
+ record. For example, you can get the current DMA hardware
+ pointer via <constant>runtime-&gt;status-&gt;hw_ptr</constant>.
+ </para>
+
+ <para>
+ The DMA application pointer can be referred via
+ <constant>runtime-&gt;control</constant>, which points to the
+ struct <structname>snd_pcm_mmap_control</structname> record.
+ However, accessing directly to this value is not recommended.
+ </para>
+ </section>
+
+ <section id="pcm-interface-runtime-private">
+ <title>Private Data</title>
+ <para>
+ You can allocate a record for the substream and store it in
+ <constant>runtime-&gt;private_data</constant>. Usually, this
+ is done in
+ <link linkend="pcm-interface-operators-open-callback"><citetitle>
+ the open callback</citetitle></link>.
+ Don't mix this with <constant>pcm-&gt;private_data</constant>.
+ The <constant>pcm-&gt;private_data</constant> usually points to the
+ chip instance assigned statically at the creation of PCM, while the
+ <constant>runtime-&gt;private_data</constant> points to a dynamic
+ data structure created at the PCM open callback.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_xxx_open(struct snd_pcm_substream *substream)
+ {
+ struct my_pcm_data *data;
+ ....
+ data = kmalloc(sizeof(*data), GFP_KERNEL);
+ substream->runtime->private_data = data;
+ ....
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The allocated object must be released in
+ <link linkend="pcm-interface-operators-open-callback"><citetitle>
+ the close callback</citetitle></link>.
+ </para>
+ </section>
+
+ <section id="pcm-interface-runtime-intr">
+ <title>Interrupt Callbacks</title>
+ <para>
+ The field <structfield>transfer_ack_begin</structfield> and
+ <structfield>transfer_ack_end</structfield> are called at
+ the beginning and at the end of
+ <function>snd_pcm_period_elapsed()</function>, respectively.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="pcm-interface-operators">
+ <title>Operators</title>
+ <para>
+ OK, now let me give details about each pcm callback
+ (<parameter>ops</parameter>). In general, every callback must
+ return 0 if successful, or a negative error number
+ such as <constant>-EINVAL</constant>. To choose an appropriate
+ error number, it is advised to check what value other parts of
+ the kernel return when the same kind of request fails.
+ </para>
+
+ <para>
+ The callback function takes at least the argument with
+ <structname>snd_pcm_substream</structname> pointer. To retrieve
+ the chip record from the given substream instance, you can use the
+ following macro.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ int xxx() {
+ struct mychip *chip = snd_pcm_substream_chip(substream);
+ ....
+ }
+]]>
+ </programlisting>
+ </informalexample>
+
+ The macro reads <constant>substream-&gt;private_data</constant>,
+ which is a copy of <constant>pcm-&gt;private_data</constant>.
+ You can override the former if you need to assign different data
+ records per PCM substream. For example, the cmi8330 driver assigns
+ different private_data for playback and capture directions,
+ because it uses two different codecs (SB- and AD-compatible) for
+ different directions.
+ </para>
+
+ <section id="pcm-interface-operators-open-callback">
+ <title>open callback</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_xxx_open(struct snd_pcm_substream *substream);
+]]>
+ </programlisting>
+ </informalexample>
+
+ This is called when a pcm substream is opened.
+ </para>
+
+ <para>
+ At least, here you have to initialize the runtime-&gt;hw
+ record. Typically, this is done by like this:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_xxx_open(struct snd_pcm_substream *substream)
+ {
+ struct mychip *chip = snd_pcm_substream_chip(substream);
+ struct snd_pcm_runtime *runtime = substream->runtime;
+
+ runtime->hw = snd_mychip_playback_hw;
+ return 0;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+
+ where <parameter>snd_mychip_playback_hw</parameter> is the
+ pre-defined hardware description.
+ </para>
+
+ <para>
+ You can allocate a private data in this callback, as described
+ in <link linkend="pcm-interface-runtime-private"><citetitle>
+ Private Data</citetitle></link> section.
+ </para>
+
+ <para>
+ If the hardware configuration needs more constraints, set the
+ hardware constraints here, too.
+ See <link linkend="pcm-interface-constraints"><citetitle>
+ Constraints</citetitle></link> for more details.
+ </para>
+ </section>
+
+ <section id="pcm-interface-operators-close-callback">
+ <title>close callback</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_xxx_close(struct snd_pcm_substream *substream);
+]]>
+ </programlisting>
+ </informalexample>
+
+ Obviously, this is called when a pcm substream is closed.
+ </para>
+
+ <para>
+ Any private instance for a pcm substream allocated in the
+ open callback will be released here.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_xxx_close(struct snd_pcm_substream *substream)
+ {
+ ....
+ kfree(substream->runtime->private_data);
+ ....
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+ </section>
+
+ <section id="pcm-interface-operators-ioctl-callback">
+ <title>ioctl callback</title>
+ <para>
+ This is used for any special call to pcm ioctls. But
+ usually you can pass a generic ioctl callback,
+ <function>snd_pcm_lib_ioctl</function>.
+ </para>
+ </section>
+
+ <section id="pcm-interface-operators-hw-params-callback">
+ <title>hw_params callback</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
+ struct snd_pcm_hw_params *hw_params);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ This is called when the hardware parameter
+ (<structfield>hw_params</structfield>) is set
+ up by the application,
+ that is, once when the buffer size, the period size, the
+ format, etc. are defined for the pcm substream.
+ </para>
+
+ <para>
+ Many hardware setups should be done in this callback,
+ including the allocation of buffers.
+ </para>
+
+ <para>
+ Parameters to be initialized are retrieved by
+ <function>params_xxx()</function> macros. To allocate
+ buffer, you can call a helper function,
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
+]]>
+ </programlisting>
+ </informalexample>
+
+ <function>snd_pcm_lib_malloc_pages()</function> is available
+ only when the DMA buffers have been pre-allocated.
+ See the section <link
+ linkend="buffer-and-memory-buffer-types"><citetitle>
+ Buffer Types</citetitle></link> for more details.
+ </para>
+
+ <para>
+ Note that this and <structfield>prepare</structfield> callbacks
+ may be called multiple times per initialization.
+ For example, the OSS emulation may
+ call these callbacks at each change via its ioctl.
+ </para>
+
+ <para>
+ Thus, you need to be careful not to allocate the same buffers
+ many times, which will lead to memory leaks! Calling the
+ helper function above many times is OK. It will release the
+ previous buffer automatically when it was already allocated.
+ </para>
+
+ <para>
+ Another note is that this callback is non-atomic
+ (schedulable). This is important, because the
+ <structfield>trigger</structfield> callback
+ is atomic (non-schedulable). That is, mutexes or any
+ schedule-related functions are not available in
+ <structfield>trigger</structfield> callback.
+ Please see the subsection
+ <link linkend="pcm-interface-atomicity"><citetitle>
+ Atomicity</citetitle></link> for details.
+ </para>
+ </section>
+
+ <section id="pcm-interface-operators-hw-free-callback">
+ <title>hw_free callback</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ This is called to release the resources allocated via
+ <structfield>hw_params</structfield>. For example, releasing the
+ buffer via
+ <function>snd_pcm_lib_malloc_pages()</function> is done by
+ calling the following:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_pcm_lib_free_pages(substream);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ This function is always called before the close callback is called.
+ Also, the callback may be called multiple times, too.
+ Keep track whether the resource was already released.
+ </para>
+ </section>
+
+ <section id="pcm-interface-operators-prepare-callback">
+ <title>prepare callback</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_xxx_prepare(struct snd_pcm_substream *substream);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ This callback is called when the pcm is
+ <quote>prepared</quote>. You can set the format type, sample
+ rate, etc. here. The difference from
+ <structfield>hw_params</structfield> is that the
+ <structfield>prepare</structfield> callback will be called each
+ time
+ <function>snd_pcm_prepare()</function> is called, i.e. when
+ recovering after underruns, etc.
+ </para>
+
+ <para>
+ Note that this callback is now non-atomic.
+ You can use schedule-related functions safely in this callback.
+ </para>
+
+ <para>
+ In this and the following callbacks, you can refer to the
+ values via the runtime record,
+ substream-&gt;runtime.
+ For example, to get the current
+ rate, format or channels, access to
+ runtime-&gt;rate,
+ runtime-&gt;format or
+ runtime-&gt;channels, respectively.
+ The physical address of the allocated buffer is set to
+ runtime-&gt;dma_area. The buffer and period sizes are
+ in runtime-&gt;buffer_size and runtime-&gt;period_size,
+ respectively.
+ </para>
+
+ <para>
+ Be careful that this callback will be called many times at
+ each setup, too.
+ </para>
+ </section>
+
+ <section id="pcm-interface-operators-trigger-callback">
+ <title>trigger callback</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
+]]>
+ </programlisting>
+ </informalexample>
+
+ This is called when the pcm is started, stopped or paused.
+ </para>
+
+ <para>
+ Which action is specified in the second argument,
+ <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
+ <filename>&lt;sound/pcm.h&gt;</filename>. At least,
+ the <constant>START</constant> and <constant>STOP</constant>
+ commands must be defined in this callback.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ switch (cmd) {
+ case SNDRV_PCM_TRIGGER_START:
+ /* do something to start the PCM engine */
+ break;
+ case SNDRV_PCM_TRIGGER_STOP:
+ /* do something to stop the PCM engine */
+ break;
+ default:
+ return -EINVAL;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ When the pcm supports the pause operation (given in the info
+ field of the hardware table), the <constant>PAUSE_PUSE</constant>
+ and <constant>PAUSE_RELEASE</constant> commands must be
+ handled here, too. The former is the command to pause the pcm,
+ and the latter to restart the pcm again.
+ </para>
+
+ <para>
+ When the pcm supports the suspend/resume operation,
+ regardless of full or partial suspend/resume support,
+ the <constant>SUSPEND</constant> and <constant>RESUME</constant>
+ commands must be handled, too.
+ These commands are issued when the power-management status is
+ changed. Obviously, the <constant>SUSPEND</constant> and
+ <constant>RESUME</constant> commands
+ suspend and resume the pcm substream, and usually, they
+ are identical to the <constant>STOP</constant> and
+ <constant>START</constant> commands, respectively.
+ See the <link linkend="power-management"><citetitle>
+ Power Management</citetitle></link> section for details.
+ </para>
+
+ <para>
+ As mentioned, this callback is atomic. You cannot call
+ functions which may sleep.
+ The trigger callback should be as minimal as possible,
+ just really triggering the DMA. The other stuff should be
+ initialized hw_params and prepare callbacks properly
+ beforehand.
+ </para>
+ </section>
+
+ <section id="pcm-interface-operators-pointer-callback">
+ <title>pointer callback</title>
+ <para>
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
+]]>
+ </programlisting>
+ </informalexample>
+
+ This callback is called when the PCM middle layer inquires
+ the current hardware position on the buffer. The position must
+ be returned in frames,
+ ranging from 0 to buffer_size - 1.
+ </para>
+
+ <para>
+ This is called usually from the buffer-update routine in the
+ pcm middle layer, which is invoked when
+ <function>snd_pcm_period_elapsed()</function> is called in the
+ interrupt routine. Then the pcm middle layer updates the
+ position and calculates the available space, and wakes up the
+ sleeping poll threads, etc.
+ </para>
+
+ <para>
+ This callback is also atomic.
+ </para>
+ </section>
+
+ <section id="pcm-interface-operators-copy-silence">
+ <title>copy and silence callbacks</title>
+ <para>
+ These callbacks are not mandatory, and can be omitted in
+ most cases. These callbacks are used when the hardware buffer
+ cannot be in the normal memory space. Some chips have their
+ own buffer on the hardware which is not mappable. In such a
+ case, you have to transfer the data manually from the memory
+ buffer to the hardware buffer. Or, if the buffer is
+ non-contiguous on both physical and virtual memory spaces,
+ these callbacks must be defined, too.
+ </para>
+
+ <para>
+ If these two callbacks are defined, copy and set-silence
+ operations are done by them. The detailed will be described in
+ the later section <link
+ linkend="buffer-and-memory"><citetitle>Buffer and Memory
+ Management</citetitle></link>.
+ </para>
+ </section>
+
+ <section id="pcm-interface-operators-ack">
+ <title>ack callback</title>
+ <para>
+ This callback is also not mandatory. This callback is called
+ when the appl_ptr is updated in read or write operations.
+ Some drivers like emu10k1-fx and cs46xx need to track the
+ current appl_ptr for the internal buffer, and this callback
+ is useful only for such a purpose.
+ </para>
+ <para>
+ This callback is atomic.
+ </para>
+ </section>
+
+ <section id="pcm-interface-operators-page-callback">
+ <title>page callback</title>
+
+ <para>
+ This callback is optional too. This callback is used
+ mainly for non-contiguous buffers. The mmap calls this
+ callback to get the page address. Some examples will be
+ explained in the later section <link
+ linkend="buffer-and-memory"><citetitle>Buffer and Memory
+ Management</citetitle></link>, too.
+ </para>
+ </section>
+ </section>
+
+ <section id="pcm-interface-interrupt-handler">
+ <title>Interrupt Handler</title>
+ <para>
+ The rest of pcm stuff is the PCM interrupt handler. The
+ role of PCM interrupt handler in the sound driver is to update
+ the buffer position and to tell the PCM middle layer when the
+ buffer position goes across the prescribed period size. To
+ inform this, call the <function>snd_pcm_period_elapsed()</function>
+ function.
+ </para>
+
+ <para>
+ There are several types of sound chips to generate the interrupts.
+ </para>
+
+ <section id="pcm-interface-interrupt-handler-boundary">
+ <title>Interrupts at the period (fragment) boundary</title>
+ <para>
+ This is the most frequently found type: the hardware
+ generates an interrupt at each period boundary.
+ In this case, you can call
+ <function>snd_pcm_period_elapsed()</function> at each
+ interrupt.
+ </para>
+
+ <para>
+ <function>snd_pcm_period_elapsed()</function> takes the
+ substream pointer as its argument. Thus, you need to keep the
+ substream pointer accessible from the chip instance. For
+ example, define substream field in the chip record to hold the
+ current running substream pointer, and set the pointer value
+ at open callback (and reset at close callback).
+ </para>
+
+ <para>
+ If you acquire a spinlock in the interrupt handler, and the
+ lock is used in other pcm callbacks, too, then you have to
+ release the lock before calling
+ <function>snd_pcm_period_elapsed()</function>, because
+ <function>snd_pcm_period_elapsed()</function> calls other pcm
+ callbacks inside.
+ </para>
+
+ <para>
+ Typical code would be like:
+
+ <example>
+ <title>Interrupt Handler Case #1</title>
+ <programlisting>
+<![CDATA[
+ static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
+ {
+ struct mychip *chip = dev_id;
+ spin_lock(&chip->lock);
+ ....
+ if (pcm_irq_invoked(chip)) {
+ /* call updater, unlock before it */
+ spin_unlock(&chip->lock);
+ snd_pcm_period_elapsed(chip->substream);
+ spin_lock(&chip->lock);
+ /* acknowledge the interrupt if necessary */
+ }
+ ....
+ spin_unlock(&chip->lock);
+ return IRQ_HANDLED;
+ }
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </section>
+
+ <section id="pcm-interface-interrupt-handler-timer">
+ <title>High frequency timer interrupts</title>
+ <para>
+ This happense when the hardware doesn't generate interrupts
+ at the period boundary but issues timer interrupts at a fixed
+ timer rate (e.g. es1968 or ymfpci drivers).
+ In this case, you need to check the current hardware
+ position and accumulate the processed sample length at each
+ interrupt. When the accumulated size exceeds the period
+ size, call
+ <function>snd_pcm_period_elapsed()</function> and reset the
+ accumulator.
+ </para>
+
+ <para>
+ Typical code would be like the following.
+
+ <example>
+ <title>Interrupt Handler Case #2</title>
+ <programlisting>
+<![CDATA[
+ static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
+ {
+ struct mychip *chip = dev_id;
+ spin_lock(&chip->lock);
+ ....
+ if (pcm_irq_invoked(chip)) {
+ unsigned int last_ptr, size;
+ /* get the current hardware pointer (in frames) */
+ last_ptr = get_hw_ptr(chip);
+ /* calculate the processed frames since the
+ * last update
+ */
+ if (last_ptr < chip->last_ptr)
+ size = runtime->buffer_size + last_ptr
+ - chip->last_ptr;
+ else
+ size = last_ptr - chip->last_ptr;
+ /* remember the last updated point */
+ chip->last_ptr = last_ptr;
+ /* accumulate the size */
+ chip->size += size;
+ /* over the period boundary? */
+ if (chip->size >= runtime->period_size) {
+ /* reset the accumulator */
+ chip->size %= runtime->period_size;
+ /* call updater */
+ spin_unlock(&chip->lock);
+ snd_pcm_period_elapsed(substream);
+ spin_lock(&chip->lock);
+ }
+ /* acknowledge the interrupt if necessary */
+ }
+ ....
+ spin_unlock(&chip->lock);
+ return IRQ_HANDLED;
+ }
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </section>
+
+ <section id="pcm-interface-interrupt-handler-both">
+ <title>On calling <function>snd_pcm_period_elapsed()</function></title>
+ <para>
+ In both cases, even if more than one period are elapsed, you
+ don't have to call
+ <function>snd_pcm_period_elapsed()</function> many times. Call
+ only once. And the pcm layer will check the current hardware
+ pointer and update to the latest status.
+ </para>
+ </section>
+ </section>
+
+ <section id="pcm-interface-atomicity">
+ <title>Atomicity</title>
+ <para>
+ One of the most important (and thus difficult to debug) problems
+ in kernel programming are race conditions.
+ In the Linux kernel, they are usually avoided via spin-locks, mutexes
+ or semaphores. In general, if a race condition can happen
+ in an interrupt handler, it has to be managed atomically, and you
+ have to use a spinlock to protect the critical session. If the
+ critical section is not in interrupt handler code and
+ if taking a relatively long time to execute is acceptable, you
+ should use mutexes or semaphores instead.
+ </para>
+
+ <para>
+ As already seen, some pcm callbacks are atomic and some are
+ not. For example, the <parameter>hw_params</parameter> callback is
+ non-atomic, while <parameter>trigger</parameter> callback is
+ atomic. This means, the latter is called already in a spinlock
+ held by the PCM middle layer. Please take this atomicity into
+ account when you choose a locking scheme in the callbacks.
+ </para>
+
+ <para>
+ In the atomic callbacks, you cannot use functions which may call
+ <function>schedule</function> or go to
+ <function>sleep</function>. Semaphores and mutexes can sleep,
+ and hence they cannot be used inside the atomic callbacks
+ (e.g. <parameter>trigger</parameter> callback).
+ To implement some delay in such a callback, please use
+ <function>udelay()</function> or <function>mdelay()</function>.
+ </para>
+
+ <para>
+ All three atomic callbacks (trigger, pointer, and ack) are
+ called with local interrupts disabled.
+ </para>
+
+ </section>
+ <section id="pcm-interface-constraints">
+ <title>Constraints</title>
+ <para>
+ If your chip supports unconventional sample rates, or only the
+ limited samples, you need to set a constraint for the
+ condition.
+ </para>
+
+ <para>
+ For example, in order to restrict the sample rates in the some
+ supported values, use
+ <function>snd_pcm_hw_constraint_list()</function>.
+ You need to call this function in the open callback.
+
+ <example>
+ <title>Example of Hardware Constraints</title>
+ <programlisting>
+<![CDATA[
+ static unsigned int rates[] =
+ {4000, 10000, 22050, 44100};
+ static struct snd_pcm_hw_constraint_list constraints_rates = {
+ .count = ARRAY_SIZE(rates),
+ .list = rates,
+ .mask = 0,
+ };
+
+ static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
+ {
+ int err;
+ ....
+ err = snd_pcm_hw_constraint_list(substream->runtime, 0,
+ SNDRV_PCM_HW_PARAM_RATE,
+ &constraints_rates);
+ if (err < 0)
+ return err;
+ ....
+ }
+]]>
+ </programlisting>
+ </example>
+ </para>
+
+ <para>
+ There are many different constraints.
+ Look at <filename>sound/pcm.h</filename> for a complete list.
+ You can even define your own constraint rules.
+ For example, let's suppose my_chip can manage a substream of 1 channel
+ if and only if the format is S16_LE, otherwise it supports any format
+ specified in the <structname>snd_pcm_hardware</structname> structure (or in any
+ other constraint_list). You can build a rule like this:
+
+ <example>
+ <title>Example of Hardware Constraints for Channels</title>
+ <programlisting>
+<![CDATA[
+ static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
+ struct snd_pcm_hw_rule *rule)
+ {
+ struct snd_interval *c = hw_param_interval(params,
+ SNDRV_PCM_HW_PARAM_CHANNELS);
+ struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
+ struct snd_mask fmt;
+
+ snd_mask_any(&fmt); /* Init the struct */
+ if (c->min < 2) {
+ fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
+ return snd_mask_refine(f, &fmt);
+ }
+ return 0;
+ }
+]]>
+ </programlisting>
+ </example>
+ </para>
+
+ <para>
+ Then you need to call this function to add your rule:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
+ hw_rule_channels_by_format, 0, SNDRV_PCM_HW_PARAM_FORMAT,
+ -1);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The rule function is called when an application sets the number of
+ channels. But an application can set the format before the number of
+ channels. Thus you also need to define the inverse rule:
+
+ <example>
+ <title>Example of Hardware Constraints for Channels</title>
+ <programlisting>
+<![CDATA[
+ static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
+ struct snd_pcm_hw_rule *rule)
+ {
+ struct snd_interval *c = hw_param_interval(params,
+ SNDRV_PCM_HW_PARAM_CHANNELS);
+ struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
+ struct snd_interval ch;
+
+ snd_interval_any(&ch);
+ if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
+ ch.min = ch.max = 1;
+ ch.integer = 1;
+ return snd_interval_refine(c, &ch);
+ }
+ return 0;
+ }
+]]>
+ </programlisting>
+ </example>
+ </para>
+
+ <para>
+ ...and in the open callback:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
+ hw_rule_format_by_channels, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
+ -1);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ I won't give more details here, rather I
+ would like to say, <quote>Luke, use the source.</quote>
+ </para>
+ </section>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- Control Interface -->
+<!-- ****************************************************** -->
+ <chapter id="control-interface">
+ <title>Control Interface</title>
+
+ <section id="control-interface-general">
+ <title>General</title>
+ <para>
+ The control interface is used widely for many switches,
+ sliders, etc. which are accessed from user-space. Its most
+ important use is the mixer interface. In other words, since ALSA
+ 0.9.x, all the mixer stuff is implemented on the control kernel API.
+ </para>
+
+ <para>
+ ALSA has a well-defined AC97 control module. If your chip
+ supports only the AC97 and nothing else, you can skip this
+ section.
+ </para>
+
+ <para>
+ The control API is defined in
+ <filename>&lt;sound/control.h&gt;</filename>.
+ Include this file if you want to add your own controls.
+ </para>
+ </section>
+
+ <section id="control-interface-definition">
+ <title>Definition of Controls</title>
+ <para>
+ To create a new control, you need to define the
+ following three
+ callbacks: <structfield>info</structfield>,
+ <structfield>get</structfield> and
+ <structfield>put</structfield>. Then, define a
+ struct <structname>snd_kcontrol_new</structname> record, such as:
+
+ <example>
+ <title>Definition of a Control</title>
+ <programlisting>
+<![CDATA[
+ static struct snd_kcontrol_new my_control __devinitdata = {
+ .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
+ .name = "PCM Playback Switch",
+ .index = 0,
+ .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
+ .private_value = 0xffff,
+ .info = my_control_info,
+ .get = my_control_get,
+ .put = my_control_put
+ };
+]]>
+ </programlisting>
+ </example>
+ </para>
+
+ <para>
+ Most likely the control is created via
+ <function>snd_ctl_new1()</function>, and in such a case, you can
+ add the <parameter>__devinitdata</parameter> prefix to the
+ definition as above.
+ </para>
+
+ <para>
+ The <structfield>iface</structfield> field specifies the control
+ type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
+ is usually <constant>MIXER</constant>.
+ Use <constant>CARD</constant> for global controls that are not
+ logically part of the mixer.
+ If the control is closely associated with some specific device on
+ the sound card, use <constant>HWDEP</constant>,
+ <constant>PCM</constant>, <constant>RAWMIDI</constant>,
+ <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
+ specify the device number with the
+ <structfield>device</structfield> and
+ <structfield>subdevice</structfield> fields.
+ </para>
+
+ <para>
+ The <structfield>name</structfield> is the name identifier
+ string. Since ALSA 0.9.x, the control name is very important,
+ because its role is classified from its name. There are
+ pre-defined standard control names. The details are described in
+ the <link linkend="control-interface-control-names"><citetitle>
+ Control Names</citetitle></link> subsection.
+ </para>
+
+ <para>
+ The <structfield>index</structfield> field holds the index number
+ of this control. If there are several different controls with
+ the same name, they can be distinguished by the index
+ number. This is the case when
+ several codecs exist on the card. If the index is zero, you can
+ omit the definition above.
+ </para>
+
+ <para>
+ The <structfield>access</structfield> field contains the access
+ type of this control. Give the combination of bit masks,
+ <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
+ The details will be explained in
+ the <link linkend="control-interface-access-flags"><citetitle>
+ Access Flags</citetitle></link> subsection.
+ </para>
+
+ <para>
+ The <structfield>private_value</structfield> field contains
+ an arbitrary long integer value for this record. When using
+ the generic <structfield>info</structfield>,
+ <structfield>get</structfield> and
+ <structfield>put</structfield> callbacks, you can pass a value
+ through this field. If several small numbers are necessary, you can
+ combine them in bitwise. Or, it's possible to give a pointer
+ (casted to unsigned long) of some record to this field, too.
+ </para>
+
+ <para>
+ The <structfield>tlv</structfield> field can be used to provide
+ metadata about the control; see the
+ <link linkend="control-interface-tlv">
+ <citetitle>Metadata</citetitle></link> subsection.
+ </para>
+
+ <para>
+ The other three are
+ <link linkend="control-interface-callbacks"><citetitle>
+ callback functions</citetitle></link>.
+ </para>
+ </section>
+
+ <section id="control-interface-control-names">
+ <title>Control Names</title>
+ <para>
+ There are some standards to define the control names. A
+ control is usually defined from the three parts as
+ <quote>SOURCE DIRECTION FUNCTION</quote>.
+ </para>
+
+ <para>
+ The first, <constant>SOURCE</constant>, specifies the source
+ of the control, and is a string such as <quote>Master</quote>,
+ <quote>PCM</quote>, <quote>CD</quote> and
+ <quote>Line</quote>. There are many pre-defined sources.
+ </para>
+
+ <para>
+ The second, <constant>DIRECTION</constant>, is one of the
+ following strings according to the direction of the control:
+ <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
+ Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
+ be omitted, meaning both playback and capture directions.
+ </para>
+
+ <para>
+ The third, <constant>FUNCTION</constant>, is one of the
+ following strings according to the function of the control:
+ <quote>Switch</quote>, <quote>Volume</quote> and
+ <quote>Route</quote>.
+ </para>
+
+ <para>
+ The example of control names are, thus, <quote>Master Capture
+ Switch</quote> or <quote>PCM Playback Volume</quote>.
+ </para>
+
+ <para>
+ There are some exceptions:
+ </para>
+
+ <section id="control-interface-control-names-global">
+ <title>Global capture and playback</title>
+ <para>
+ <quote>Capture Source</quote>, <quote>Capture Switch</quote>
+ and <quote>Capture Volume</quote> are used for the global
+ capture (input) source, switch and volume. Similarly,
+ <quote>Playback Switch</quote> and <quote>Playback
+ Volume</quote> are used for the global output gain switch and
+ volume.
+ </para>
+ </section>
+
+ <section id="control-interface-control-names-tone">
+ <title>Tone-controls</title>
+ <para>
+ tone-control switch and volumes are specified like
+ <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
+ Switch</quote>, <quote>Tone Control - Bass</quote>,
+ <quote>Tone Control - Center</quote>.
+ </para>
+ </section>
+
+ <section id="control-interface-control-names-3d">
+ <title>3D controls</title>
+ <para>
+ 3D-control switches and volumes are specified like <quote>3D
+ Control - XXX</quote>, e.g. <quote>3D Control -
+ Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
+ Control - Space</quote>.
+ </para>
+ </section>
+
+ <section id="control-interface-control-names-mic">
+ <title>Mic boost</title>
+ <para>
+ Mic-boost switch is set as <quote>Mic Boost</quote> or
+ <quote>Mic Boost (6dB)</quote>.
+ </para>
+
+ <para>
+ More precise information can be found in
+ <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
+ </para>
+ </section>
+ </section>
+
+ <section id="control-interface-access-flags">
+ <title>Access Flags</title>
+
+ <para>
+ The access flag is the bitmask which specifies the access type
+ of the given control. The default access type is
+ <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>,
+ which means both read and write are allowed to this control.
+ When the access flag is omitted (i.e. = 0), it is
+ considered as <constant>READWRITE</constant> access as default.
+ </para>
+
+ <para>
+ When the control is read-only, pass
+ <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
+ In this case, you don't have to define
+ the <structfield>put</structfield> callback.
+ Similarly, when the control is write-only (although it's a rare
+ case), you can use the <constant>WRITE</constant> flag instead, and
+ you don't need the <structfield>get</structfield> callback.
+ </para>
+
+ <para>
+ If the control value changes frequently (e.g. the VU meter),
+ <constant>VOLATILE</constant> flag should be given. This means
+ that the control may be changed without
+ <link linkend="control-interface-change-notification"><citetitle>
+ notification</citetitle></link>. Applications should poll such
+ a control constantly.
+ </para>
+
+ <para>
+ When the control is inactive, set
+ the <constant>INACTIVE</constant> flag, too.
+ There are <constant>LOCK</constant> and
+ <constant>OWNER</constant> flags to change the write
+ permissions.
+ </para>
+
+ </section>
+
+ <section id="control-interface-callbacks">
+ <title>Callbacks</title>
+
+ <section id="control-interface-callbacks-info">
+ <title>info callback</title>
+ <para>
+ The <structfield>info</structfield> callback is used to get
+ detailed information on this control. This must store the
+ values of the given struct <structname>snd_ctl_elem_info</structname>
+ object. For example, for a boolean control with a single
+ element:
+
+ <example>
+ <title>Example of info callback</title>
+ <programlisting>
+<![CDATA[
+ static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
+ struct snd_ctl_elem_info *uinfo)
+ {
+ uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
+ uinfo->count = 1;
+ uinfo->value.integer.min = 0;
+ uinfo->value.integer.max = 1;
+ return 0;
+ }
+]]>
+ </programlisting>
+ </example>
+ </para>
+
+ <para>
+ The <structfield>type</structfield> field specifies the type
+ of the control. There are <constant>BOOLEAN</constant>,
+ <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
+ <constant>BYTES</constant>, <constant>IEC958</constant> and
+ <constant>INTEGER64</constant>. The
+ <structfield>count</structfield> field specifies the
+ number of elements in this control. For example, a stereo
+ volume would have count = 2. The
+ <structfield>value</structfield> field is a union, and
+ the values stored are depending on the type. The boolean and
+ integer types are identical.
+ </para>
+
+ <para>
+ The enumerated type is a bit different from others. You'll
+ need to set the string for the currently given item index.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
+ struct snd_ctl_elem_info *uinfo)
+ {
+ static char *texts[4] = {
+ "First", "Second", "Third", "Fourth"
+ };
+ uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
+ uinfo->count = 1;
+ uinfo->value.enumerated.items = 4;
+ if (uinfo->value.enumerated.item > 3)
+ uinfo->value.enumerated.item = 3;
+ strcpy(uinfo->value.enumerated.name,
+ texts[uinfo->value.enumerated.item]);
+ return 0;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Some common info callbacks are available for your convenience:
+ <function>snd_ctl_boolean_mono_info()</function> and
+ <function>snd_ctl_boolean_stereo_info()</function>.
+ Obviously, the former is an info callback for a mono channel
+ boolean item, just like <function>snd_myctl_mono_info</function>
+ above, and the latter is for a stereo channel boolean item.
+ </para>
+
+ </section>
+
+ <section id="control-interface-callbacks-get">
+ <title>get callback</title>
+
+ <para>
+ This callback is used to read the current value of the
+ control and to return to user-space.
+ </para>
+
+ <para>
+ For example,
+
+ <example>
+ <title>Example of get callback</title>
+ <programlisting>
+<![CDATA[
+ static int snd_myctl_get(struct snd_kcontrol *kcontrol,
+ struct snd_ctl_elem_value *ucontrol)
+ {
+ struct mychip *chip = snd_kcontrol_chip(kcontrol);
+ ucontrol->value.integer.value[0] = get_some_value(chip);
+ return 0;
+ }
+]]>
+ </programlisting>
+ </example>
+ </para>
+
+ <para>
+ The <structfield>value</structfield> field depends on
+ the type of control as well as on the info callback. For example,
+ the sb driver uses this field to store the register offset,
+ the bit-shift and the bit-mask. The
+ <structfield>private_value</structfield> field is set as follows:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ .private_value = reg | (shift << 16) | (mask << 24)
+]]>
+ </programlisting>
+ </informalexample>
+ and is retrieved in callbacks like
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
+ struct snd_ctl_elem_value *ucontrol)
+ {
+ int reg = kcontrol->private_value & 0xff;
+ int shift = (kcontrol->private_value >> 16) & 0xff;
+ int mask = (kcontrol->private_value >> 24) & 0xff;
+ ....
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ In the <structfield>get</structfield> callback,
+ you have to fill all the elements if the
+ control has more than one elements,
+ i.e. <structfield>count</structfield> &gt; 1.
+ In the example above, we filled only one element
+ (<structfield>value.integer.value[0]</structfield>) since it's
+ assumed as <structfield>count</structfield> = 1.
+ </para>
+ </section>
+
+ <section id="control-interface-callbacks-put">
+ <title>put callback</title>
+
+ <para>
+ This callback is used to write a value from user-space.
+ </para>
+
+ <para>
+ For example,
+
+ <example>
+ <title>Example of put callback</title>
+ <programlisting>
+<![CDATA[
+ static int snd_myctl_put(struct snd_kcontrol *kcontrol,
+ struct snd_ctl_elem_value *ucontrol)
+ {
+ struct mychip *chip = snd_kcontrol_chip(kcontrol);
+ int changed = 0;
+ if (chip->current_value !=
+ ucontrol->value.integer.value[0]) {
+ change_current_value(chip,
+ ucontrol->value.integer.value[0]);
+ changed = 1;
+ }
+ return changed;
+ }
+]]>
+ </programlisting>
+ </example>
+
+ As seen above, you have to return 1 if the value is
+ changed. If the value is not changed, return 0 instead.
+ If any fatal error happens, return a negative error code as
+ usual.
+ </para>
+
+ <para>
+ As in the <structfield>get</structfield> callback,
+ when the control has more than one elements,
+ all elements must be evaluated in this callback, too.
+ </para>
+ </section>
+
+ <section id="control-interface-callbacks-all">
+ <title>Callbacks are not atomic</title>
+ <para>
+ All these three callbacks are basically not atomic.
+ </para>
+ </section>
+ </section>
+
+ <section id="control-interface-constructor">
+ <title>Constructor</title>
+ <para>
+ When everything is ready, finally we can create a new
+ control. To create a control, there are two functions to be
+ called, <function>snd_ctl_new1()</function> and
+ <function>snd_ctl_add()</function>.
+ </para>
+
+ <para>
+ In the simplest way, you can do like this:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
+ if (err < 0)
+ return err;
+]]>
+ </programlisting>
+ </informalexample>
+
+ where <parameter>my_control</parameter> is the
+ struct <structname>snd_kcontrol_new</structname> object defined above, and chip
+ is the object pointer to be passed to
+ kcontrol-&gt;private_data
+ which can be referred to in callbacks.
+ </para>
+
+ <para>
+ <function>snd_ctl_new1()</function> allocates a new
+ <structname>snd_kcontrol</structname> instance (that's why the definition
+ of <parameter>my_control</parameter> can be with
+ the <parameter>__devinitdata</parameter>
+ prefix), and <function>snd_ctl_add</function> assigns the given
+ control component to the card.
+ </para>
+ </section>
+
+ <section id="control-interface-change-notification">
+ <title>Change Notification</title>
+ <para>
+ If you need to change and update a control in the interrupt
+ routine, you can call <function>snd_ctl_notify()</function>. For
+ example,
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
+]]>
+ </programlisting>
+ </informalexample>
+
+ This function takes the card pointer, the event-mask, and the
+ control id pointer for the notification. The event-mask
+ specifies the types of notification, for example, in the above
+ example, the change of control values is notified.
+ The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
+ to be notified.
+ You can find some examples in <filename>es1938.c</filename> or
+ <filename>es1968.c</filename> for hardware volume interrupts.
+ </para>
+ </section>
+
+ <section id="control-interface-tlv">
+ <title>Metadata</title>
+ <para>
+ To provide information about the dB values of a mixer control, use
+ on of the <constant>DECLARE_TLV_xxx</constant> macros from
+ <filename>&lt;sound/tlv.h&gt;</filename> to define a variable
+ containing this information, set the<structfield>tlv.p
+ </structfield> field to point to this variable, and include the
+ <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
+ <structfield>access</structfield> field; like this:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
+
+ static struct snd_kcontrol_new my_control __devinitdata = {
+ ...
+ .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
+ SNDRV_CTL_ELEM_ACCESS_TLV_READ,
+ ...
+ .tlv.p = db_scale_my_control,
+ };
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The <function>DECLARE_TLV_DB_SCALE</function> macro defines
+ information about a mixer control where each step in the control's
+ value changes the dB value by a constant dB amount.
+ The first parameter is the name of the variable to be defined.
+ The second parameter is the minimum value, in units of 0.01 dB.
+ The third parameter is the step size, in units of 0.01 dB.
+ Set the fourth parameter to 1 if the minimum value actually mutes
+ the control.
+ </para>
+
+ <para>
+ The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
+ information about a mixer control where the control's value affects
+ the output linearly.
+ The first parameter is the name of the variable to be defined.
+ The second parameter is the minimum value, in units of 0.01 dB.
+ The third parameter is the maximum value, in units of 0.01 dB.
+ If the minimum value mutes the control, set the second parameter to
+ <constant>TLV_DB_GAIN_MUTE</constant>.
+ </para>
+ </section>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- API for AC97 Codec -->
+<!-- ****************************************************** -->
+ <chapter id="api-ac97">
+ <title>API for AC97 Codec</title>
+
+ <section>
+ <title>General</title>
+ <para>
+ The ALSA AC97 codec layer is a well-defined one, and you don't
+ have to write much code to control it. Only low-level control
+ routines are necessary. The AC97 codec API is defined in
+ <filename>&lt;sound/ac97_codec.h&gt;</filename>.
+ </para>
+ </section>
+
+ <section id="api-ac97-example">
+ <title>Full Code Example</title>
+ <para>
+ <example>
+ <title>Example of AC97 Interface</title>
+ <programlisting>
+<![CDATA[
+ struct mychip {
+ ....
+ struct snd_ac97 *ac97;
+ ....
+ };
+
+ static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
+ unsigned short reg)
+ {
+ struct mychip *chip = ac97->private_data;
+ ....
+ /* read a register value here from the codec */
+ return the_register_value;
+ }
+
+ static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
+ unsigned short reg, unsigned short val)
+ {
+ struct mychip *chip = ac97->private_data;
+ ....
+ /* write the given register value to the codec */
+ }
+
+ static int snd_mychip_ac97(struct mychip *chip)
+ {
+ struct snd_ac97_bus *bus;
+ struct snd_ac97_template ac97;
+ int err;
+ static struct snd_ac97_bus_ops ops = {
+ .write = snd_mychip_ac97_write,
+ .read = snd_mychip_ac97_read,
+ };
+
+ err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
+ if (err < 0)
+ return err;
+ memset(&ac97, 0, sizeof(ac97));
+ ac97.private_data = chip;
+ return snd_ac97_mixer(bus, &ac97, &chip->ac97);
+ }
+
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </section>
+
+ <section id="api-ac97-constructor">
+ <title>Constructor</title>
+ <para>
+ To create an ac97 instance, first call <function>snd_ac97_bus</function>
+ with an <type>ac97_bus_ops_t</type> record with callback functions.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_ac97_bus *bus;
+ static struct snd_ac97_bus_ops ops = {
+ .write = snd_mychip_ac97_write,
+ .read = snd_mychip_ac97_read,
+ };
+
+ snd_ac97_bus(card, 0, &ops, NULL, &pbus);
+]]>
+ </programlisting>
+ </informalexample>
+
+ The bus record is shared among all belonging ac97 instances.
+ </para>
+
+ <para>
+ And then call <function>snd_ac97_mixer()</function> with an
+ struct <structname>snd_ac97_template</structname>
+ record together with the bus pointer created above.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_ac97_template ac97;
+ int err;
+
+ memset(&ac97, 0, sizeof(ac97));
+ ac97.private_data = chip;
+ snd_ac97_mixer(bus, &ac97, &chip->ac97);
+]]>
+ </programlisting>
+ </informalexample>
+
+ where chip-&gt;ac97 is a pointer to a newly created
+ <type>ac97_t</type> instance.
+ In this case, the chip pointer is set as the private data, so that
+ the read/write callback functions can refer to this chip instance.
+ This instance is not necessarily stored in the chip
+ record. If you need to change the register values from the
+ driver, or need the suspend/resume of ac97 codecs, keep this
+ pointer to pass to the corresponding functions.
+ </para>
+ </section>
+
+ <section id="api-ac97-callbacks">
+ <title>Callbacks</title>
+ <para>
+ The standard callbacks are <structfield>read</structfield> and
+ <structfield>write</structfield>. Obviously they
+ correspond to the functions for read and write accesses to the
+ hardware low-level codes.
+ </para>
+
+ <para>
+ The <structfield>read</structfield> callback returns the
+ register value specified in the argument.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
+ unsigned short reg)
+ {
+ struct mychip *chip = ac97->private_data;
+ ....
+ return the_register_value;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+
+ Here, the chip can be cast from ac97-&gt;private_data.
+ </para>
+
+ <para>
+ Meanwhile, the <structfield>write</structfield> callback is
+ used to set the register value.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
+ unsigned short reg, unsigned short val)
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ These callbacks are non-atomic like the control API callbacks.
+ </para>
+
+ <para>
+ There are also other callbacks:
+ <structfield>reset</structfield>,
+ <structfield>wait</structfield> and
+ <structfield>init</structfield>.
+ </para>
+
+ <para>
+ The <structfield>reset</structfield> callback is used to reset
+ the codec. If the chip requires a special kind of reset, you can
+ define this callback.
+ </para>
+
+ <para>
+ The <structfield>wait</structfield> callback is used to
+ add some waiting time in the standard initialization of the codec. If the
+ chip requires the extra waiting time, define this callback.
+ </para>
+
+ <para>
+ The <structfield>init</structfield> callback is used for
+ additional initialization of the codec.
+ </para>
+ </section>
+
+ <section id="api-ac97-updating-registers">
+ <title>Updating Registers in The Driver</title>
+ <para>
+ If you need to access to the codec from the driver, you can
+ call the following functions:
+ <function>snd_ac97_write()</function>,
+ <function>snd_ac97_read()</function>,
+ <function>snd_ac97_update()</function> and
+ <function>snd_ac97_update_bits()</function>.
+ </para>
+
+ <para>
+ Both <function>snd_ac97_write()</function> and
+ <function>snd_ac97_update()</function> functions are used to
+ set a value to the given register
+ (<constant>AC97_XXX</constant>). The difference between them is
+ that <function>snd_ac97_update()</function> doesn't write a
+ value if the given value has been already set, while
+ <function>snd_ac97_write()</function> always rewrites the
+ value.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_ac97_write(ac97, AC97_MASTER, 0x8080);
+ snd_ac97_update(ac97, AC97_MASTER, 0x8080);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ <function>snd_ac97_read()</function> is used to read the value
+ of the given register. For example,
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ value = snd_ac97_read(ac97, AC97_MASTER);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ <function>snd_ac97_update_bits()</function> is used to update
+ some bits in the given register.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_ac97_update_bits(ac97, reg, mask, value);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Also, there is a function to change the sample rate (of a
+ given register such as
+ <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
+ DRA is supported by the codec:
+ <function>snd_ac97_set_rate()</function>.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The following registers are available to set the rate:
+ <constant>AC97_PCM_MIC_ADC_RATE</constant>,
+ <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
+ <constant>AC97_PCM_LR_ADC_RATE</constant>,
+ <constant>AC97_SPDIF</constant>. When
+ <constant>AC97_SPDIF</constant> is specified, the register is
+ not really changed but the corresponding IEC958 status bits will
+ be updated.
+ </para>
+ </section>
+
+ <section id="api-ac97-clock-adjustment">
+ <title>Clock Adjustment</title>
+ <para>
+ In some chips, the clock of the codec isn't 48000 but using a
+ PCI clock (to save a quartz!). In this case, change the field
+ bus-&gt;clock to the corresponding
+ value. For example, intel8x0
+ and es1968 drivers have their own function to read from the clock.
+ </para>
+ </section>
+
+ <section id="api-ac97-proc-files">
+ <title>Proc Files</title>
+ <para>
+ The ALSA AC97 interface will create a proc file such as
+ <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
+ <filename>ac97#0-0+regs</filename>. You can refer to these files to
+ see the current status and registers of the codec.
+ </para>
+ </section>
+
+ <section id="api-ac97-multiple-codecs">
+ <title>Multiple Codecs</title>
+ <para>
+ When there are several codecs on the same card, you need to
+ call <function>snd_ac97_mixer()</function> multiple times with
+ ac97.num=1 or greater. The <structfield>num</structfield> field
+ specifies the codec number.
+ </para>
+
+ <para>
+ If you set up multiple codecs, you either need to write
+ different callbacks for each codec or check
+ ac97-&gt;num in the callback routines.
+ </para>
+ </section>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- MIDI (MPU401-UART) Interface -->
+<!-- ****************************************************** -->
+ <chapter id="midi-interface">
+ <title>MIDI (MPU401-UART) Interface</title>
+
+ <section id="midi-interface-general">
+ <title>General</title>
+ <para>
+ Many soundcards have built-in MIDI (MPU401-UART)
+ interfaces. When the soundcard supports the standard MPU401-UART
+ interface, most likely you can use the ALSA MPU401-UART API. The
+ MPU401-UART API is defined in
+ <filename>&lt;sound/mpu401.h&gt;</filename>.
+ </para>
+
+ <para>
+ Some soundchips have a similar but slightly different
+ implementation of mpu401 stuff. For example, emu10k1 has its own
+ mpu401 routines.
+ </para>
+ </section>
+
+ <section id="midi-interface-constructor">
+ <title>Constructor</title>
+ <para>
+ To create a rawmidi object, call
+ <function>snd_mpu401_uart_new()</function>.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_rawmidi *rmidi;
+ snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
+ irq, irq_flags, &rmidi);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The first argument is the card pointer, and the second is the
+ index of this component. You can create up to 8 rawmidi
+ devices.
+ </para>
+
+ <para>
+ The third argument is the type of the hardware,
+ <constant>MPU401_HW_XXX</constant>. If it's not a special one,
+ you can use <constant>MPU401_HW_MPU401</constant>.
+ </para>
+
+ <para>
+ The 4th argument is the I/O port address. Many
+ backward-compatible MPU401 have an I/O port such as 0x330. Or, it
+ might be a part of its own PCI I/O region. It depends on the
+ chip design.
+ </para>
+
+ <para>
+ The 5th argument is a bitflag for additional information.
+ When the I/O port address above is part of the PCI I/O
+ region, the MPU401 I/O port might have been already allocated
+ (reserved) by the driver itself. In such a case, pass a bit flag
+ <constant>MPU401_INFO_INTEGRATED</constant>,
+ and the mpu401-uart layer will allocate the I/O ports by itself.
+ </para>
+
+ <para>
+ When the controller supports only the input or output MIDI stream,
+ pass the <constant>MPU401_INFO_INPUT</constant> or
+ <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
+ Then the rawmidi instance is created as a single stream.
+ </para>
+
+ <para>
+ <constant>MPU401_INFO_MMIO</constant> bitflag is used to change
+ the access method to MMIO (via readb and writeb) instead of
+ iob and outb. In this case, you have to pass the iomapped address
+ to <function>snd_mpu401_uart_new()</function>.
+ </para>
+
+ <para>
+ When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
+ stream isn't checked in the default interrupt handler. The driver
+ needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
+ by itself to start processing the output stream in the irq handler.
+ </para>
+
+ <para>
+ Usually, the port address corresponds to the command port and
+ port + 1 corresponds to the data port. If not, you may change
+ the <structfield>cport</structfield> field of
+ struct <structname>snd_mpu401</structname> manually
+ afterward. However, <structname>snd_mpu401</structname> pointer is not
+ returned explicitly by
+ <function>snd_mpu401_uart_new()</function>. You need to cast
+ rmidi-&gt;private_data to
+ <structname>snd_mpu401</structname> explicitly,
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_mpu401 *mpu;
+ mpu = rmidi->private_data;
+]]>
+ </programlisting>
+ </informalexample>
+
+ and reset the cport as you like:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ mpu->cport = my_own_control_port;
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The 6th argument specifies the irq number for UART. If the irq
+ is already allocated, pass 0 to the 7th argument
+ (<parameter>irq_flags</parameter>). Otherwise, pass the flags
+ for irq allocation
+ (<constant>SA_XXX</constant> bits) to it, and the irq will be
+ reserved by the mpu401-uart layer. If the card doesn't generate
+ UART interrupts, pass -1 as the irq number. Then a timer
+ interrupt will be invoked for polling.
+ </para>
+ </section>
+
+ <section id="midi-interface-interrupt-handler">
+ <title>Interrupt Handler</title>
+ <para>
+ When the interrupt is allocated in
+ <function>snd_mpu401_uart_new()</function>, the private
+ interrupt handler is used, hence you don't have anything else to do
+ than creating the mpu401 stuff. Otherwise, you have to call
+ <function>snd_mpu401_uart_interrupt()</function> explicitly when
+ a UART interrupt is invoked and checked in your own interrupt
+ handler.
+ </para>
+
+ <para>
+ In this case, you need to pass the private_data of the
+ returned rawmidi object from
+ <function>snd_mpu401_uart_new()</function> as the second
+ argument of <function>snd_mpu401_uart_interrupt()</function>.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+ </section>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- RawMIDI Interface -->
+<!-- ****************************************************** -->
+ <chapter id="rawmidi-interface">
+ <title>RawMIDI Interface</title>
+
+ <section id="rawmidi-interface-overview">
+ <title>Overview</title>
+
+ <para>
+ The raw MIDI interface is used for hardware MIDI ports that can
+ be accessed as a byte stream. It is not used for synthesizer
+ chips that do not directly understand MIDI.
+ </para>
+
+ <para>
+ ALSA handles file and buffer management. All you have to do is
+ to write some code to move data between the buffer and the
+ hardware.
+ </para>
+
+ <para>
+ The rawmidi API is defined in
+ <filename>&lt;sound/rawmidi.h&gt;</filename>.
+ </para>
+ </section>
+
+ <section id="rawmidi-interface-constructor">
+ <title>Constructor</title>
+
+ <para>
+ To create a rawmidi device, call the
+ <function>snd_rawmidi_new</function> function:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_rawmidi *rmidi;
+ err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
+ if (err < 0)
+ return err;
+ rmidi->private_data = chip;
+ strcpy(rmidi->name, "My MIDI");
+ rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
+ SNDRV_RAWMIDI_INFO_INPUT |
+ SNDRV_RAWMIDI_INFO_DUPLEX;
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The first argument is the card pointer, the second argument is
+ the ID string.
+ </para>
+
+ <para>
+ The third argument is the index of this component. You can
+ create up to 8 rawmidi devices.
+ </para>
+
+ <para>
+ The fourth and fifth arguments are the number of output and
+ input substreams, respectively, of this device (a substream is
+ the equivalent of a MIDI port).
+ </para>
+
+ <para>
+ Set the <structfield>info_flags</structfield> field to specify
+ the capabilities of the device.
+ Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
+ at least one output port,
+ <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
+ least one input port,
+ and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
+ can handle output and input at the same time.
+ </para>
+
+ <para>
+ After the rawmidi device is created, you need to set the
+ operators (callbacks) for each substream. There are helper
+ functions to set the operators for all the substreams of a device:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
+ snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The operators are usually defined like this:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static struct snd_rawmidi_ops snd_mymidi_output_ops = {
+ .open = snd_mymidi_output_open,
+ .close = snd_mymidi_output_close,
+ .trigger = snd_mymidi_output_trigger,
+ };
+]]>
+ </programlisting>
+ </informalexample>
+ These callbacks are explained in the <link
+ linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
+ section.
+ </para>
+
+ <para>
+ If there are more than one substream, you should give a
+ unique name to each of them:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_rawmidi_substream *substream;
+ list_for_each_entry(substream,
+ &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
+ list {
+ sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
+ }
+ /* same for SNDRV_RAWMIDI_STREAM_INPUT */
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+ </section>
+
+ <section id="rawmidi-interface-callbacks">
+ <title>Callbacks</title>
+
+ <para>
+ In all the callbacks, the private data that you've set for the
+ rawmidi device can be accessed as
+ substream-&gt;rmidi-&gt;private_data.
+ <!-- <code> isn't available before DocBook 4.3 -->
+ </para>
+
+ <para>
+ If there is more than one port, your callbacks can determine the
+ port index from the struct snd_rawmidi_substream data passed to each
+ callback:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_rawmidi_substream *substream;
+ int index = substream->number;
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <section id="rawmidi-interface-op-open">
+ <title><function>open</function> callback</title>
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_xxx_open(struct snd_rawmidi_substream *substream);
+]]>
+ </programlisting>
+ </informalexample>
+
+ <para>
+ This is called when a substream is opened.
+ You can initialize the hardware here, but you shouldn't
+ start transmitting/receiving data yet.
+ </para>
+ </section>
+
+ <section id="rawmidi-interface-op-close">
+ <title><function>close</function> callback</title>
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int snd_xxx_close(struct snd_rawmidi_substream *substream);
+]]>
+ </programlisting>
+ </informalexample>
+
+ <para>
+ Guess what.
+ </para>
+
+ <para>
+ The <function>open</function> and <function>close</function>
+ callbacks of a rawmidi device are serialized with a mutex,
+ and can sleep.
+ </para>
+ </section>
+
+ <section id="rawmidi-interface-op-trigger-out">
+ <title><function>trigger</function> callback for output
+ substreams</title>
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
+]]>
+ </programlisting>
+ </informalexample>
+
+ <para>
+ This is called with a nonzero <parameter>up</parameter>
+ parameter when there is some data in the substream buffer that
+ must be transmitted.
+ </para>
+
+ <para>
+ To read data from the buffer, call
+ <function>snd_rawmidi_transmit_peek</function>. It will
+ return the number of bytes that have been read; this will be
+ less than the number of bytes requested when there are no more
+ data in the buffer.
+ After the data have been transmitted successfully, call
+ <function>snd_rawmidi_transmit_ack</function> to remove the
+ data from the substream buffer:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ unsigned char data;
+ while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
+ if (snd_mychip_try_to_transmit(data))
+ snd_rawmidi_transmit_ack(substream, 1);
+ else
+ break; /* hardware FIFO full */
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ If you know beforehand that the hardware will accept data, you
+ can use the <function>snd_rawmidi_transmit</function> function
+ which reads some data and removes them from the buffer at once:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ while (snd_mychip_transmit_possible()) {
+ unsigned char data;
+ if (snd_rawmidi_transmit(substream, &data, 1) != 1)
+ break; /* no more data */
+ snd_mychip_transmit(data);
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ If you know beforehand how many bytes you can accept, you can
+ use a buffer size greater than one with the
+ <function>snd_rawmidi_transmit*</function> functions.
+ </para>
+
+ <para>
+ The <function>trigger</function> callback must not sleep. If
+ the hardware FIFO is full before the substream buffer has been
+ emptied, you have to continue transmitting data later, either
+ in an interrupt handler, or with a timer if the hardware
+ doesn't have a MIDI transmit interrupt.
+ </para>
+
+ <para>
+ The <function>trigger</function> callback is called with a
+ zero <parameter>up</parameter> parameter when the transmission
+ of data should be aborted.
+ </para>
+ </section>
+
+ <section id="rawmidi-interface-op-trigger-in">
+ <title><function>trigger</function> callback for input
+ substreams</title>
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
+]]>
+ </programlisting>
+ </informalexample>
+
+ <para>
+ This is called with a nonzero <parameter>up</parameter>
+ parameter to enable receiving data, or with a zero
+ <parameter>up</parameter> parameter do disable receiving data.
+ </para>
+
+ <para>
+ The <function>trigger</function> callback must not sleep; the
+ actual reading of data from the device is usually done in an
+ interrupt handler.
+ </para>
+
+ <para>
+ When data reception is enabled, your interrupt handler should
+ call <function>snd_rawmidi_receive</function> for all received
+ data:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ void snd_mychip_midi_interrupt(...)
+ {
+ while (mychip_midi_available()) {
+ unsigned char data;
+ data = mychip_midi_read();
+ snd_rawmidi_receive(substream, &data, 1);
+ }
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+ </section>
+
+ <section id="rawmidi-interface-op-drain">
+ <title><function>drain</function> callback</title>
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
+]]>
+ </programlisting>
+ </informalexample>
+
+ <para>
+ This is only used with output substreams. This function should wait
+ until all data read from the substream buffer have been transmitted.
+ This ensures that the device can be closed and the driver unloaded
+ without losing data.
+ </para>
+
+ <para>
+ This callback is optional. If you do not set
+ <structfield>drain</structfield> in the struct snd_rawmidi_ops
+ structure, ALSA will simply wait for 50&nbsp;milliseconds
+ instead.
+ </para>
+ </section>
+ </section>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- Miscellaneous Devices -->
+<!-- ****************************************************** -->
+ <chapter id="misc-devices">
+ <title>Miscellaneous Devices</title>
+
+ <section id="misc-devices-opl3">
+ <title>FM OPL3</title>
+ <para>
+ The FM OPL3 is still used in many chips (mainly for backward
+ compatibility). ALSA has a nice OPL3 FM control layer, too. The
+ OPL3 API is defined in
+ <filename>&lt;sound/opl3.h&gt;</filename>.
+ </para>
+
+ <para>
+ FM registers can be directly accessed through the direct-FM API,
+ defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
+ ALSA native mode, FM registers are accessed through
+ the Hardware-Dependant Device direct-FM extension API, whereas in
+ OSS compatible mode, FM registers can be accessed with the OSS
+ direct-FM compatible API in <filename>/dev/dmfmX</filename> device.
+ </para>
+
+ <para>
+ To create the OPL3 component, you have two functions to
+ call. The first one is a constructor for the <type>opl3_t</type>
+ instance.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_opl3 *opl3;
+ snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
+ integrated, &opl3);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The first argument is the card pointer, the second one is the
+ left port address, and the third is the right port address. In
+ most cases, the right port is placed at the left port + 2.
+ </para>
+
+ <para>
+ The fourth argument is the hardware type.
+ </para>
+
+ <para>
+ When the left and right ports have been already allocated by
+ the card driver, pass non-zero to the fifth argument
+ (<parameter>integrated</parameter>). Otherwise, the opl3 module will
+ allocate the specified ports by itself.
+ </para>
+
+ <para>
+ When the accessing the hardware requires special method
+ instead of the standard I/O access, you can create opl3 instance
+ separately with <function>snd_opl3_new()</function>.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_opl3 *opl3;
+ snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Then set <structfield>command</structfield>,
+ <structfield>private_data</structfield> and
+ <structfield>private_free</structfield> for the private
+ access function, the private data and the destructor.
+ The l_port and r_port are not necessarily set. Only the
+ command must be set properly. You can retrieve the data
+ from the opl3-&gt;private_data field.
+ </para>
+
+ <para>
+ After creating the opl3 instance via <function>snd_opl3_new()</function>,
+ call <function>snd_opl3_init()</function> to initialize the chip to the
+ proper state. Note that <function>snd_opl3_create()</function> always
+ calls it internally.
+ </para>
+
+ <para>
+ If the opl3 instance is created successfully, then create a
+ hwdep device for this opl3.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_hwdep *opl3hwdep;
+ snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The first argument is the <type>opl3_t</type> instance you
+ created, and the second is the index number, usually 0.
+ </para>
+
+ <para>
+ The third argument is the index-offset for the sequencer
+ client assigned to the OPL3 port. When there is an MPU401-UART,
+ give 1 for here (UART always takes 0).
+ </para>
+ </section>
+
+ <section id="misc-devices-hardware-dependent">
+ <title>Hardware-Dependent Devices</title>
+ <para>
+ Some chips need user-space access for special
+ controls or for loading the micro code. In such a case, you can
+ create a hwdep (hardware-dependent) device. The hwdep API is
+ defined in <filename>&lt;sound/hwdep.h&gt;</filename>. You can
+ find examples in opl3 driver or
+ <filename>isa/sb/sb16_csp.c</filename>.
+ </para>
+
+ <para>
+ The creation of the <type>hwdep</type> instance is done via
+ <function>snd_hwdep_new()</function>.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_hwdep *hw;
+ snd_hwdep_new(card, "My HWDEP", 0, &hw);
+]]>
+ </programlisting>
+ </informalexample>
+
+ where the third argument is the index number.
+ </para>
+
+ <para>
+ You can then pass any pointer value to the
+ <parameter>private_data</parameter>.
+ If you assign a private data, you should define the
+ destructor, too. The destructor function is set in
+ the <structfield>private_free</structfield> field.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
+ hw->private_data = p;
+ hw->private_free = mydata_free;
+]]>
+ </programlisting>
+ </informalexample>
+
+ and the implementation of the destructor would be:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static void mydata_free(struct snd_hwdep *hw)
+ {
+ struct mydata *p = hw->private_data;
+ kfree(p);
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The arbitrary file operations can be defined for this
+ instance. The file operators are defined in
+ the <parameter>ops</parameter> table. For example, assume that
+ this chip needs an ioctl.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ hw->ops.open = mydata_open;
+ hw->ops.ioctl = mydata_ioctl;
+ hw->ops.release = mydata_release;
+]]>
+ </programlisting>
+ </informalexample>
+
+ And implement the callback functions as you like.
+ </para>
+ </section>
+
+ <section id="misc-devices-IEC958">
+ <title>IEC958 (S/PDIF)</title>
+ <para>
+ Usually the controls for IEC958 devices are implemented via
+ the control interface. There is a macro to compose a name string for
+ IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
+ defined in <filename>&lt;include/asound.h&gt;</filename>.
+ </para>
+
+ <para>
+ There are some standard controls for IEC958 status bits. These
+ controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
+ and the size of element is fixed as 4 bytes array
+ (value.iec958.status[x]). For the <structfield>info</structfield>
+ callback, you don't specify
+ the value field for this type (the count field must be set,
+ though).
+ </para>
+
+ <para>
+ <quote>IEC958 Playback Con Mask</quote> is used to return the
+ bit-mask for the IEC958 status bits of consumer mode. Similarly,
+ <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
+ professional mode. They are read-only controls, and are defined
+ as MIXER controls (iface =
+ <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).
+ </para>
+
+ <para>
+ Meanwhile, <quote>IEC958 Playback Default</quote> control is
+ defined for getting and setting the current default IEC958
+ bits. Note that this one is usually defined as a PCM control
+ (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
+ although in some places it's defined as a MIXER control.
+ </para>
+
+ <para>
+ In addition, you can define the control switches to
+ enable/disable or to set the raw bit mode. The implementation
+ will depend on the chip, but the control should be named as
+ <quote>IEC958 xxx</quote>, preferably using
+ the <function>SNDRV_CTL_NAME_IEC958()</function> macro.
+ </para>
+
+ <para>
+ You can find several cases, for example,
+ <filename>pci/emu10k1</filename>,
+ <filename>pci/ice1712</filename>, or
+ <filename>pci/cmipci.c</filename>.
+ </para>
+ </section>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- Buffer and Memory Management -->
+<!-- ****************************************************** -->
+ <chapter id="buffer-and-memory">
+ <title>Buffer and Memory Management</title>
+
+ <section id="buffer-and-memory-buffer-types">
+ <title>Buffer Types</title>
+ <para>
+ ALSA provides several different buffer allocation functions
+ depending on the bus and the architecture. All these have a
+ consistent API. The allocation of physically-contiguous pages is
+ done via
+ <function>snd_malloc_xxx_pages()</function> function, where xxx
+ is the bus type.
+ </para>
+
+ <para>
+ The allocation of pages with fallback is
+ <function>snd_malloc_xxx_pages_fallback()</function>. This
+ function tries to allocate the specified pages but if the pages
+ are not available, it tries to reduce the page sizes until
+ enough space is found.
+ </para>
+
+ <para>
+ The release the pages, call
+ <function>snd_free_xxx_pages()</function> function.
+ </para>
+
+ <para>
+ Usually, ALSA drivers try to allocate and reserve
+ a large contiguous physical space
+ at the time the module is loaded for the later use.
+ This is called <quote>pre-allocation</quote>.
+ As already written, you can call the following function at
+ pcm instance construction time (in the case of PCI bus).
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
+ snd_dma_pci_data(pci), size, max);
+]]>
+ </programlisting>
+ </informalexample>
+
+ where <parameter>size</parameter> is the byte size to be
+ pre-allocated and the <parameter>max</parameter> is the maximum
+ size to be changed via the <filename>prealloc</filename> proc file.
+ The allocator will try to get an area as large as possible
+ within the given size.
+ </para>
+
+ <para>
+ The second argument (type) and the third argument (device pointer)
+ are dependent on the bus.
+ In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
+ as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
+ For the continuous buffer unrelated to the bus can be pre-allocated
+ with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
+ <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
+ where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
+ use.
+ For the PCI scatter-gather buffers, use
+ <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
+ <function>snd_dma_pci_data(pci)</function>
+ (see the
+ <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
+ </citetitle></link> section).
+ </para>
+
+ <para>
+ Once the buffer is pre-allocated, you can use the
+ allocator in the <structfield>hw_params</structfield> callback:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_pcm_lib_malloc_pages(substream, size);
+]]>
+ </programlisting>
+ </informalexample>
+
+ Note that you have to pre-allocate to use this function.
+ </para>
+ </section>
+
+ <section id="buffer-and-memory-external-hardware">
+ <title>External Hardware Buffers</title>
+ <para>
+ Some chips have their own hardware buffers and the DMA
+ transfer from the host memory is not available. In such a case,
+ you need to either 1) copy/set the audio data directly to the
+ external hardware buffer, or 2) make an intermediate buffer and
+ copy/set the data from it to the external hardware buffer in
+ interrupts (or in tasklets, preferably).
+ </para>
+
+ <para>
+ The first case works fine if the external hardware buffer is large
+ enough. This method doesn't need any extra buffers and thus is
+ more effective. You need to define the
+ <structfield>copy</structfield> and
+ <structfield>silence</structfield> callbacks for
+ the data transfer. However, there is a drawback: it cannot
+ be mmapped. The examples are GUS's GF1 PCM or emu8000's
+ wavetable PCM.
+ </para>
+
+ <para>
+ The second case allows for mmap on the buffer, although you have
+ to handle an interrupt or a tasklet to transfer the data
+ from the intermediate buffer to the hardware buffer. You can find an
+ example in the vxpocket driver.
+ </para>
+
+ <para>
+ Another case is when the chip uses a PCI memory-map
+ region for the buffer instead of the host memory. In this case,
+ mmap is available only on certain architectures like the Intel one.
+ In non-mmap mode, the data cannot be transferred as in the normal
+ way. Thus you need to define the <structfield>copy</structfield> and
+ <structfield>silence</structfield> callbacks as well,
+ as in the cases above. The examples are found in
+ <filename>rme32.c</filename> and <filename>rme96.c</filename>.
+ </para>
+
+ <para>
+ The implementation of the <structfield>copy</structfield> and
+ <structfield>silence</structfield> callbacks depends upon
+ whether the hardware supports interleaved or non-interleaved
+ samples. The <structfield>copy</structfield> callback is
+ defined like below, a bit
+ differently depending whether the direction is playback or
+ capture:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int playback_copy(struct snd_pcm_substream *substream, int channel,
+ snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
+ static int capture_copy(struct snd_pcm_substream *substream, int channel,
+ snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ In the case of interleaved samples, the second argument
+ (<parameter>channel</parameter>) is not used. The third argument
+ (<parameter>pos</parameter>) points the
+ current position offset in frames.
+ </para>
+
+ <para>
+ The meaning of the fourth argument is different between
+ playback and capture. For playback, it holds the source data
+ pointer, and for capture, it's the destination data pointer.
+ </para>
+
+ <para>
+ The last argument is the number of frames to be copied.
+ </para>
+
+ <para>
+ What you have to do in this callback is again different
+ between playback and capture directions. In the
+ playback case, you copy the given amount of data
+ (<parameter>count</parameter>) at the specified pointer
+ (<parameter>src</parameter>) to the specified offset
+ (<parameter>pos</parameter>) on the hardware buffer. When
+ coded like memcpy-like way, the copy would be like:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
+ frames_to_bytes(runtime, count));
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ For the capture direction, you copy the given amount of
+ data (<parameter>count</parameter>) at the specified offset
+ (<parameter>pos</parameter>) on the hardware buffer to the
+ specified pointer (<parameter>dst</parameter>).
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
+ frames_to_bytes(runtime, count));
+]]>
+ </programlisting>
+ </informalexample>
+
+ Note that both the position and the amount of data are given
+ in frames.
+ </para>
+
+ <para>
+ In the case of non-interleaved samples, the implementation
+ will be a bit more complicated.
+ </para>
+
+ <para>
+ You need to check the channel argument, and if it's -1, copy
+ the whole channels. Otherwise, you have to copy only the
+ specified channel. Please check
+ <filename>isa/gus/gus_pcm.c</filename> as an example.
+ </para>
+
+ <para>
+ The <structfield>silence</structfield> callback is also
+ implemented in a similar way.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int silence(struct snd_pcm_substream *substream, int channel,
+ snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The meanings of arguments are the same as in the
+ <structfield>copy</structfield>
+ callback, although there is no <parameter>src/dst</parameter>
+ argument. In the case of interleaved samples, the channel
+ argument has no meaning, as well as on
+ <structfield>copy</structfield> callback.
+ </para>
+
+ <para>
+ The role of <structfield>silence</structfield> callback is to
+ set the given amount
+ (<parameter>count</parameter>) of silence data at the
+ specified offset (<parameter>pos</parameter>) on the hardware
+ buffer. Suppose that the data format is signed (that is, the
+ silent-data is 0), and the implementation using a memset-like
+ function would be like:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
+ frames_to_bytes(runtime, count));
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ In the case of non-interleaved samples, again, the
+ implementation becomes a bit more complicated. See, for example,
+ <filename>isa/gus/gus_pcm.c</filename>.
+ </para>
+ </section>
+
+ <section id="buffer-and-memory-non-contiguous">
+ <title>Non-Contiguous Buffers</title>
+ <para>
+ If your hardware supports the page table as in emu10k1 or the
+ buffer descriptors as in via82xx, you can use the scatter-gather
+ (SG) DMA. ALSA provides an interface for handling SG-buffers.
+ The API is provided in <filename>&lt;sound/pcm.h&gt;</filename>.
+ </para>
+
+ <para>
+ For creating the SG-buffer handler, call
+ <function>snd_pcm_lib_preallocate_pages()</function> or
+ <function>snd_pcm_lib_preallocate_pages_for_all()</function>
+ with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
+ in the PCM constructor like other PCI pre-allocator.
+ You need to pass <function>snd_dma_pci_data(pci)</function>,
+ where pci is the struct <structname>pci_dev</structname> pointer
+ of the chip as well.
+ The <type>struct snd_sg_buf</type> instance is created as
+ substream-&gt;dma_private. You can cast
+ the pointer like:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Then call <function>snd_pcm_lib_malloc_pages()</function>
+ in the <structfield>hw_params</structfield> callback
+ as well as in the case of normal PCI buffer.
+ The SG-buffer handler will allocate the non-contiguous kernel
+ pages of the given size and map them onto the virtually contiguous
+ memory. The virtual pointer is addressed in runtime-&gt;dma_area.
+ The physical address (runtime-&gt;dma_addr) is set to zero,
+ because the buffer is physically non-contigous.
+ The physical address table is set up in sgbuf-&gt;table.
+ You can get the physical address at a certain offset via
+ <function>snd_pcm_sgbuf_get_addr()</function>.
+ </para>
+
+ <para>
+ When a SG-handler is used, you need to set
+ <function>snd_pcm_sgbuf_ops_page</function> as
+ the <structfield>page</structfield> callback.
+ (See <link linkend="pcm-interface-operators-page-callback">
+ <citetitle>page callback section</citetitle></link>.)
+ </para>
+
+ <para>
+ To release the data, call
+ <function>snd_pcm_lib_free_pages()</function> in the
+ <structfield>hw_free</structfield> callback as usual.
+ </para>
+ </section>
+
+ <section id="buffer-and-memory-vmalloced">
+ <title>Vmalloc'ed Buffers</title>
+ <para>
+ It's possible to use a buffer allocated via
+ <function>vmalloc</function>, for example, for an intermediate
+ buffer. Since the allocated pages are not contiguous, you need
+ to set the <structfield>page</structfield> callback to obtain
+ the physical address at every offset.
+ </para>
+
+ <para>
+ The implementation of <structfield>page</structfield> callback
+ would be like this:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ #include <linux/vmalloc.h>
+
+ /* get the physical page pointer on the given offset */
+ static struct page *mychip_page(struct snd_pcm_substream *substream,
+ unsigned long offset)
+ {
+ void *pageptr = substream->runtime->dma_area + offset;
+ return vmalloc_to_page(pageptr);
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+ </section>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- Proc Interface -->
+<!-- ****************************************************** -->
+ <chapter id="proc-interface">
+ <title>Proc Interface</title>
+ <para>
+ ALSA provides an easy interface for procfs. The proc files are
+ very useful for debugging. I recommend you set up proc files if
+ you write a driver and want to get a running status or register
+ dumps. The API is found in
+ <filename>&lt;sound/info.h&gt;</filename>.
+ </para>
+
+ <para>
+ To create a proc file, call
+ <function>snd_card_proc_new()</function>.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ struct snd_info_entry *entry;
+ int err = snd_card_proc_new(card, "my-file", &entry);
+]]>
+ </programlisting>
+ </informalexample>
+
+ where the second argument specifies the name of the proc file to be
+ created. The above example will create a file
+ <filename>my-file</filename> under the card directory,
+ e.g. <filename>/proc/asound/card0/my-file</filename>.
+ </para>
+
+ <para>
+ Like other components, the proc entry created via
+ <function>snd_card_proc_new()</function> will be registered and
+ released automatically in the card registration and release
+ functions.
+ </para>
+
+ <para>
+ When the creation is successful, the function stores a new
+ instance in the pointer given in the third argument.
+ It is initialized as a text proc file for read only. To use
+ this proc file as a read-only text file as it is, set the read
+ callback with a private data via
+ <function>snd_info_set_text_ops()</function>.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_info_set_text_ops(entry, chip, my_proc_read);
+]]>
+ </programlisting>
+ </informalexample>
+
+ where the second argument (<parameter>chip</parameter>) is the
+ private data to be used in the callbacks. The third parameter
+ specifies the read buffer size and the fourth
+ (<parameter>my_proc_read</parameter>) is the callback function, which
+ is defined like
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static void my_proc_read(struct snd_info_entry *entry,
+ struct snd_info_buffer *buffer);
+]]>
+ </programlisting>
+ </informalexample>
+
+ </para>
+
+ <para>
+ In the read callback, use <function>snd_iprintf()</function> for
+ output strings, which works just like normal
+ <function>printf()</function>. For example,
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static void my_proc_read(struct snd_info_entry *entry,
+ struct snd_info_buffer *buffer)
+ {
+ struct my_chip *chip = entry->private_data;
+
+ snd_iprintf(buffer, "This is my chip!\n");
+ snd_iprintf(buffer, "Port = %ld\n", chip->port);
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The file permissions can be changed afterwards. As default, it's
+ set as read only for all users. If you want to add write
+ permission for the user (root as default), do as follows:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
+]]>
+ </programlisting>
+ </informalexample>
+
+ and set the write buffer size and the callback
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ entry->c.text.write = my_proc_write;
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ For the write callback, you can use
+ <function>snd_info_get_line()</function> to get a text line, and
+ <function>snd_info_get_str()</function> to retrieve a string from
+ the line. Some examples are found in
+ <filename>core/oss/mixer_oss.c</filename>, core/oss/and
+ <filename>pcm_oss.c</filename>.
+ </para>
+
+ <para>
+ For a raw-data proc-file, set the attributes as follows:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static struct snd_info_entry_ops my_file_io_ops = {
+ .read = my_file_io_read,
+ };
+
+ entry->content = SNDRV_INFO_CONTENT_DATA;
+ entry->private_data = chip;
+ entry->c.ops = &my_file_io_ops;
+ entry->size = 4096;
+ entry->mode = S_IFREG | S_IRUGO;
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The callback is much more complicated than the text-file
+ version. You need to use a low-level I/O functions such as
+ <function>copy_from/to_user()</function> to transfer the
+ data.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static long my_file_io_read(struct snd_info_entry *entry,
+ void *file_private_data,
+ struct file *file,
+ char *buf,
+ unsigned long count,
+ unsigned long pos)
+ {
+ long size = count;
+ if (pos + size > local_max_size)
+ size = local_max_size - pos;
+ if (copy_to_user(buf, local_data + pos, size))
+ return -EFAULT;
+ return size;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- Power Management -->
+<!-- ****************************************************** -->
+ <chapter id="power-management">
+ <title>Power Management</title>
+ <para>
+ If the chip is supposed to work with suspend/resume
+ functions, you need to add power-management code to the
+ driver. The additional code for power-management should be
+ <function>ifdef</function>'ed with
+ <constant>CONFIG_PM</constant>.
+ </para>
+
+ <para>
+ If the driver <emphasis>fully</emphasis> supports suspend/resume
+ that is, the device can be
+ properly resumed to its state when suspend was called,
+ you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
+ in the pcm info field. Usually, this is possible when the
+ registers of the chip can be safely saved and restored to
+ RAM. If this is set, the trigger callback is called with
+ <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
+ callback completes.
+ </para>
+
+ <para>
+ Even if the driver doesn't support PM fully but
+ partial suspend/resume is still possible, it's still worthy to
+ implement suspend/resume callbacks. In such a case, applications
+ would reset the status by calling
+ <function>snd_pcm_prepare()</function> and restart the stream
+ appropriately. Hence, you can define suspend/resume callbacks
+ below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
+ info flag to the PCM.
+ </para>
+
+ <para>
+ Note that the trigger with SUSPEND can always be called when
+ <function>snd_pcm_suspend_all</function> is called,
+ regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
+ The <constant>RESUME</constant> flag affects only the behavior
+ of <function>snd_pcm_resume()</function>.
+ (Thus, in theory,
+ <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
+ to be handled in the trigger callback when no
+ <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But,
+ it's better to keep it for compatibility reasons.)
+ </para>
+ <para>
+ In the earlier version of ALSA drivers, a common
+ power-management layer was provided, but it has been removed.
+ The driver needs to define the suspend/resume hooks according to
+ the bus the device is connected to. In the case of PCI drivers, the
+ callbacks look like below:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ #ifdef CONFIG_PM
+ static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
+ {
+ .... /* do things for suspend */
+ return 0;
+ }
+ static int snd_my_resume(struct pci_dev *pci)
+ {
+ .... /* do things for suspend */
+ return 0;
+ }
+ #endif
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The scheme of the real suspend job is as follows.
+
+ <orderedlist>
+ <listitem><para>Retrieve the card and the chip data.</para></listitem>
+ <listitem><para>Call <function>snd_power_change_state()</function> with
+ <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
+ power status.</para></listitem>
+ <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
+ <listitem><para>If AC97 codecs are used, call
+ <function>snd_ac97_suspend()</function> for each codec.</para></listitem>
+ <listitem><para>Save the register values if necessary.</para></listitem>
+ <listitem><para>Stop the hardware if necessary.</para></listitem>
+ <listitem><para>Disable the PCI device by calling
+ <function>pci_disable_device()</function>. Then, call
+ <function>pci_save_state()</function> at last.</para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ A typical code would be like:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
+ {
+ /* (1) */
+ struct snd_card *card = pci_get_drvdata(pci);
+ struct mychip *chip = card->private_data;
+ /* (2) */
+ snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
+ /* (3) */
+ snd_pcm_suspend_all(chip->pcm);
+ /* (4) */
+ snd_ac97_suspend(chip->ac97);
+ /* (5) */
+ snd_mychip_save_registers(chip);
+ /* (6) */
+ snd_mychip_stop_hardware(chip);
+ /* (7) */
+ pci_disable_device(pci);
+ pci_save_state(pci);
+ return 0;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ The scheme of the real resume job is as follows.
+
+ <orderedlist>
+ <listitem><para>Retrieve the card and the chip data.</para></listitem>
+ <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
+ Then enable the pci device again by calling <function>pci_enable_device()</function>.
+ Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
+ <listitem><para>Re-initialize the chip.</para></listitem>
+ <listitem><para>Restore the saved registers if necessary.</para></listitem>
+ <listitem><para>Resume the mixer, e.g. calling
+ <function>snd_ac97_resume()</function>.</para></listitem>
+ <listitem><para>Restart the hardware (if any).</para></listitem>
+ <listitem><para>Call <function>snd_power_change_state()</function> with
+ <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ A typical code would be like:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int mychip_resume(struct pci_dev *pci)
+ {
+ /* (1) */
+ struct snd_card *card = pci_get_drvdata(pci);
+ struct mychip *chip = card->private_data;
+ /* (2) */
+ pci_restore_state(pci);
+ pci_enable_device(pci);
+ pci_set_master(pci);
+ /* (3) */
+ snd_mychip_reinit_chip(chip);
+ /* (4) */
+ snd_mychip_restore_registers(chip);
+ /* (5) */
+ snd_ac97_resume(chip->ac97);
+ /* (6) */
+ snd_mychip_restart_chip(chip);
+ /* (7) */
+ snd_power_change_state(card, SNDRV_CTL_POWER_D0);
+ return 0;
+ }
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ As shown in the above, it's better to save registers after
+ suspending the PCM operations via
+ <function>snd_pcm_suspend_all()</function> or
+ <function>snd_pcm_suspend()</function>. It means that the PCM
+ streams are already stoppped when the register snapshot is
+ taken. But, remember that you don't have to restart the PCM
+ stream in the resume callback. It'll be restarted via
+ trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
+ when necessary.
+ </para>
+
+ <para>
+ OK, we have all callbacks now. Let's set them up. In the
+ initialization of the card, make sure that you can get the chip
+ data from the card instance, typically via
+ <structfield>private_data</structfield> field, in case you
+ created the chip data individually.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int __devinit snd_mychip_probe(struct pci_dev *pci,
+ const struct pci_device_id *pci_id)
+ {
+ ....
+ struct snd_card *card;
+ struct mychip *chip;
+ ....
+ card = snd_card_new(index[dev], id[dev], THIS_MODULE, NULL);
+ ....
+ chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ ....
+ card->private_data = chip;
+ ....
+ }
+]]>
+ </programlisting>
+ </informalexample>
+
+ When you created the chip data with
+ <function>snd_card_new()</function>, it's anyway accessible
+ via <structfield>private_data</structfield> field.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int __devinit snd_mychip_probe(struct pci_dev *pci,
+ const struct pci_device_id *pci_id)
+ {
+ ....
+ struct snd_card *card;
+ struct mychip *chip;
+ ....
+ card = snd_card_new(index[dev], id[dev], THIS_MODULE,
+ sizeof(struct mychip));
+ ....
+ chip = card->private_data;
+ ....
+ }
+]]>
+ </programlisting>
+ </informalexample>
+
+ </para>
+
+ <para>
+ If you need a space to save the registers, allocate the
+ buffer for it here, too, since it would be fatal
+ if you cannot allocate a memory in the suspend phase.
+ The allocated buffer should be released in the corresponding
+ destructor.
+ </para>
+
+ <para>
+ And next, set suspend/resume callbacks to the pci_driver.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static struct pci_driver driver = {
+ .name = "My Chip",
+ .id_table = snd_my_ids,
+ .probe = snd_my_probe,
+ .remove = __devexit_p(snd_my_remove),
+ #ifdef CONFIG_PM
+ .suspend = snd_my_suspend,
+ .resume = snd_my_resume,
+ #endif
+ };
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- Module Parameters -->
+<!-- ****************************************************** -->
+ <chapter id="module-parameters">
+ <title>Module Parameters</title>
+ <para>
+ There are standard module options for ALSA. At least, each
+ module should have the <parameter>index</parameter>,
+ <parameter>id</parameter> and <parameter>enable</parameter>
+ options.
+ </para>
+
+ <para>
+ If the module supports multiple cards (usually up to
+ 8 = <constant>SNDRV_CARDS</constant> cards), they should be
+ arrays. The default initial values are defined already as
+ constants for easier programming:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
+ static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
+ static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ If the module supports only a single card, they could be single
+ variables, instead. <parameter>enable</parameter> option is not
+ always necessary in this case, but it would be better to have a
+ dummy option for compatibility.
+ </para>
+
+ <para>
+ The module parameters must be declared with the standard
+ <function>module_param()()</function>,
+ <function>module_param_array()()</function> and
+ <function>MODULE_PARM_DESC()</function> macros.
+ </para>
+
+ <para>
+ The typical coding would be like below:
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ #define CARD_NAME "My Chip"
+
+ module_param_array(index, int, NULL, 0444);
+ MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
+ module_param_array(id, charp, NULL, 0444);
+ MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
+ module_param_array(enable, bool, NULL, 0444);
+ MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Also, don't forget to define the module description, classes,
+ license and devices. Especially, the recent modprobe requires to
+ define the module license as GPL, etc., otherwise the system is
+ shown as <quote>tainted</quote>.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ MODULE_DESCRIPTION("My Chip");
+ MODULE_LICENSE("GPL");
+ MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- How To Put Your Driver -->
+<!-- ****************************************************** -->
+ <chapter id="how-to-put-your-driver">
+ <title>How To Put Your Driver Into ALSA Tree</title>
+ <section>
+ <title>General</title>
+ <para>
+ So far, you've learned how to write the driver codes.
+ And you might have a question now: how to put my own
+ driver into the ALSA driver tree?
+ Here (finally :) the standard procedure is described briefly.
+ </para>
+
+ <para>
+ Suppose that you create a new PCI driver for the card
+ <quote>xyz</quote>. The card module name would be
+ snd-xyz. The new driver is usually put into the alsa-driver
+ tree, <filename>alsa-driver/pci</filename> directory in
+ the case of PCI cards.
+ Then the driver is evaluated, audited and tested
+ by developers and users. After a certain time, the driver
+ will go to the alsa-kernel tree (to the corresponding directory,
+ such as <filename>alsa-kernel/pci</filename>) and eventually
+ will be integrated into the Linux 2.6 tree (the directory would be
+ <filename>linux/sound/pci</filename>).
+ </para>
+
+ <para>
+ In the following sections, the driver code is supposed
+ to be put into alsa-driver tree. The two cases are covered:
+ a driver consisting of a single source file and one consisting
+ of several source files.
+ </para>
+ </section>
+
+ <section>
+ <title>Driver with A Single Source File</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Modify alsa-driver/pci/Makefile
+ </para>
+
+ <para>
+ Suppose you have a file xyz.c. Add the following
+ two lines
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd-xyz-objs := xyz.o
+ obj-$(CONFIG_SND_XYZ) += snd-xyz.o
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Create the Kconfig entry
+ </para>
+
+ <para>
+ Add the new entry of Kconfig for your xyz driver.
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ config SND_XYZ
+ tristate "Foobar XYZ"
+ depends on SND
+ select SND_PCM
+ help
+ Say Y here to include support for Foobar XYZ soundcard.
+
+ To compile this driver as a module, choose M here: the module
+ will be called snd-xyz.
+]]>
+ </programlisting>
+ </informalexample>
+
+ the line, select SND_PCM, specifies that the driver xyz supports
+ PCM. In addition to SND_PCM, the following components are
+ supported for select command:
+ SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
+ SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
+ Add the select command for each supported component.
+ </para>
+
+ <para>
+ Note that some selections imply the lowlevel selections.
+ For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
+ AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
+ You don't need to give the lowlevel selections again.
+ </para>
+
+ <para>
+ For the details of Kconfig script, refer to the kbuild
+ documentation.
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>
+ Run cvscompile script to re-generate the configure script and
+ build the whole stuff again.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section>
+ <title>Drivers with Several Source Files</title>
+ <para>
+ Suppose that the driver snd-xyz have several source files.
+ They are located in the new subdirectory,
+ pci/xyz.
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Add a new directory (<filename>xyz</filename>) in
+ <filename>alsa-driver/pci/Makefile</filename> as below
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ obj-$(CONFIG_SND) += xyz/
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Under the directory <filename>xyz</filename>, create a Makefile
+
+ <example>
+ <title>Sample Makefile for a driver xyz</title>
+ <programlisting>
+<![CDATA[
+ ifndef SND_TOPDIR
+ SND_TOPDIR=../..
+ endif
+
+ include $(SND_TOPDIR)/toplevel.config
+ include $(SND_TOPDIR)/Makefile.conf
+
+ snd-xyz-objs := xyz.o abc.o def.o
+
+ obj-$(CONFIG_SND_XYZ) += snd-xyz.o
+
+ include $(SND_TOPDIR)/Rules.make
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Create the Kconfig entry
+ </para>
+
+ <para>
+ This procedure is as same as in the last section.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Run cvscompile script to re-generate the configure script and
+ build the whole stuff again.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ </chapter>
+
+<!-- ****************************************************** -->
+<!-- Useful Functions -->
+<!-- ****************************************************** -->
+ <chapter id="useful-functions">
+ <title>Useful Functions</title>
+
+ <section id="useful-functions-snd-printk">
+ <title><function>snd_printk()</function> and friends</title>
+ <para>
+ ALSA provides a verbose version of the
+ <function>printk()</function> function. If a kernel config
+ <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
+ function prints the given message together with the file name
+ and the line of the caller. The <constant>KERN_XXX</constant>
+ prefix is processed as
+ well as the original <function>printk()</function> does, so it's
+ recommended to add this prefix, e.g.
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ There are also <function>printk()</function>'s for
+ debugging. <function>snd_printd()</function> can be used for
+ general debugging purposes. If
+ <constant>CONFIG_SND_DEBUG</constant> is set, this function is
+ compiled, and works just like
+ <function>snd_printk()</function>. If the ALSA is compiled
+ without the debugging flag, it's ignored.
+ </para>
+
+ <para>
+ <function>snd_printdd()</function> is compiled in only when
+ <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
+ that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
+ even if you configure the alsa-driver with
+ <option>--with-debug=full</option> option. You need to give
+ explicitly <option>--with-debug=detect</option> option instead.
+ </para>
+ </section>
+
+ <section id="useful-functions-snd-bug">
+ <title><function>snd_BUG()</function></title>
+ <para>
+ It shows the <computeroutput>BUG?</computeroutput> message and
+ stack trace as well as <function>snd_BUG_ON</function> at the point.
+ It's useful to show that a fatal error happens there.
+ </para>
+ <para>
+ When no debug flag is set, this macro is ignored.
+ </para>
+ </section>
+
+ <section id="useful-functions-snd-bug-on">
+ <title><function>snd_BUG_ON()</function></title>
+ <para>
+ <function>snd_BUG_ON()</function> macro is similar with
+ <function>WARN_ON()</function> macro. For example,
+
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ snd_BUG_ON(!pointer);
+]]>
+ </programlisting>
+ </informalexample>
+
+ or it can be used as the condition,
+ <informalexample>
+ <programlisting>
+<![CDATA[
+ if (snd_BUG_ON(non_zero_is_bug))
+ return -EINVAL;
+]]>
+ </programlisting>
+ </informalexample>
+
+ </para>
+
+ <para>
+ The macro takes an conditional expression to evaluate.
+ When <constant>CONFIG_SND_DEBUG</constant>, is set, the
+ expression is actually evaluated. If it's non-zero, it shows
+ the warning message such as
+ <computeroutput>BUG? (xxx)</computeroutput>
+ normally followed by stack trace. It returns the evaluated
+ value.
+ When no <constant>CONFIG_SND_DEBUG</constant> is set, this
+ macro always returns zero.
+ </para>
+
+ </section>
+
+ </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- Acknowledgments -->
+<!-- ****************************************************** -->
+ <chapter id="acknowledgments">
+ <title>Acknowledgments</title>
+ <para>
+ I would like to thank Phil Kerr for his help for improvement and
+ corrections of this document.
+ </para>
+ <para>
+ Kevin Conder reformatted the original plain-text to the
+ DocBook format.
+ </para>
+ <para>
+ Giuliano Pochini corrected typos and contributed the example codes
+ in the hardware constraints section.
+ </para>
+ </chapter>
+</book>
diff --git a/Documentation/sound/alsa/Joystick.txt b/Documentation/sound/alsa/Joystick.txt
new file mode 100644
index 0000000..ccda41b
--- /dev/null
+++ b/Documentation/sound/alsa/Joystick.txt
@@ -0,0 +1,86 @@
+Analog Joystick Support on ALSA Drivers
+=======================================
+ Oct. 14, 2003
+ Takashi Iwai <tiwai@suse.de>
+
+General
+-------
+
+First of all, you need to enable GAMEPORT support on Linux kernel for
+using a joystick with the ALSA driver. For the details of gameport
+support, refer to Documentation/input/joystick.txt.
+
+The joystick support of ALSA drivers is different between ISA and PCI
+cards. In the case of ISA (PnP) cards, it's usually handled by the
+independent module (ns558). Meanwhile, the ALSA PCI drivers have the
+built-in gameport support. Hence, when the ALSA PCI driver is built
+in the kernel, CONFIG_GAMEPORT must be 'y', too. Otherwise, the
+gameport support on that card will be (silently) disabled.
+
+Some adapter modules probe the physical connection of the device at
+the load time. It'd be safer to plug in the joystick device before
+loading the module.
+
+
+PCI Cards
+---------
+
+For PCI cards, the joystick is enabled when the appropriate module
+option is specified. Some drivers don't need options, and the
+joystick support is always enabled. In the former ALSA version, there
+was a dynamic control API for the joystick activation. It was
+changed, however, to the static module options because of the system
+stability and the resource management.
+
+The following PCI drivers support the joystick natively.
+
+ Driver Module Option Available Values
+ ---------------------------------------------------------------------------
+ als4000 joystick_port 0 = disable (default), 1 = auto-detect,
+ manual: any address (e.g. 0x200)
+ au88x0 N/A N/A
+ azf3328 joystick 0 = disable, 1 = enable, -1 = auto (default)
+ ens1370 joystick 0 = disable (default), 1 = enable
+ ens1371 joystick_port 0 = disable (default), 1 = auto-detect,
+ manual: 0x200, 0x208, 0x210, 0x218
+ cmipci joystick_port 0 = disable (default), 1 = auto-detect,
+ manual: any address (e.g. 0x200)
+ cs4281 N/A N/A
+ cs46xx N/A N/A
+ es1938 N/A N/A
+ es1968 joystick 0 = disable (default), 1 = enable
+ sonicvibes N/A N/A
+ trident N/A N/A
+ via82xx(*1) joystick 0 = disable (default), 1 = enable
+ ymfpci joystick_port 0 = disable (default), 1 = auto-detect,
+ manual: 0x201, 0x202, 0x204, 0x205(*2)
+ ---------------------------------------------------------------------------
+
+ *1) VIA686A/B only
+ *2) With YMF744/754 chips, the port address can be chosen arbitrarily
+
+The following drivers don't support gameport natively, but there are
+additional modules. Load the corresponding module to add the gameport
+support.
+
+ Driver Additional Module
+ -----------------------------
+ emu10k1 emu10k1-gp
+ fm801 fm801-gp
+ -----------------------------
+
+Note: the "pcigame" and "cs461x" modules are for the OSS drivers only.
+ These ALSA drivers (cs46xx, trident and au88x0) have the
+ built-in gameport support.
+
+As mentioned above, ALSA PCI drivers have the built-in gameport
+support, so you don't have to load ns558 module. Just load "joydev"
+and the appropriate adapter module (e.g. "analog").
+
+
+ISA Cards
+---------
+
+ALSA ISA drivers don't have the built-in gameport support.
+Instead, you need to load "ns558" module in addition to "joydev" and
+the adapter module (e.g. "analog").
diff --git a/Documentation/sound/alsa/MIXART.txt b/Documentation/sound/alsa/MIXART.txt
new file mode 100644
index 0000000..ef42c44
--- /dev/null
+++ b/Documentation/sound/alsa/MIXART.txt
@@ -0,0 +1,100 @@
+ Alsa driver for Digigram miXart8 and miXart8AES/EBU soundcards
+ Digigram <alsa@digigram.com>
+
+
+GENERAL
+=======
+
+The miXart8 is a multichannel audio processing and mixing soundcard
+that has 4 stereo audio inputs and 4 stereo audio outputs.
+The miXart8AES/EBU is the same with a add-on card that offers further
+4 digital stereo audio inputs and outputs.
+Furthermore the add-on card offers external clock synchronisation
+(AES/EBU, Word Clock, Time Code and Video Synchro)
+
+The mainboard has a PowerPC that offers onboard mpeg encoding and
+decoding, samplerate conversions and various effects.
+
+The driver don't work properly at all until the certain firmwares
+are loaded, i.e. no PCM nor mixer devices will appear.
+Use the mixartloader that can be found in the alsa-tools package.
+
+
+VERSION 0.1.0
+=============
+
+One miXart8 board will be represented as 4 alsa cards, each with 1
+stereo analog capture 'pcm0c' and 1 stereo analog playback 'pcm0p' device.
+With a miXart8AES/EBU there is in addition 1 stereo digital input
+'pcm1c' and 1 stereo digital output 'pcm1p' per card.
+
+Formats
+-------
+U8, S16_LE, S16_BE, S24_3LE, S24_3BE, FLOAT_LE, FLOAT_BE
+Sample rates : 8000 - 48000 Hz continuously
+
+Playback
+--------
+For instance the playback devices are configured to have max. 4
+substreams performing hardware mixing. This could be changed to a
+maximum of 24 substreams if wished.
+Mono files will be played on the left and right channel. Each channel
+can be muted for each stream to use 8 analog/digital outputs separately.
+
+Capture
+-------
+There is one substream per capture device. For instance only stereo
+formats are supported.
+
+Mixer
+-----
+<Master> and <Master Capture> : analog volume control of playback and capture PCM.
+<PCM 0-3> and <PCM Capture> : digital volume control of each analog substream.
+<AES 0-3> and <AES Capture> : digital volume control of each AES/EBU substream.
+<Monitoring> : Loopback from 'pcm0c' to 'pcm0p' with digital volume
+and mute control.
+
+Rem : for best audio quality try to keep a 0 attenuation on the PCM
+and AES volume controls which is set by 219 in the range from 0 to 255
+(about 86% with alsamixer)
+
+
+NOT YET IMPLEMENTED
+===================
+
+- external clock support (AES/EBU, Word Clock, Time Code, Video Sync)
+- MPEG audio formats
+- mono record
+- on-board effects and samplerate conversions
+- linked streams
+
+
+FIRMWARE
+========
+
+[As of 2.6.11, the firmware can be loaded automatically with hotplug
+ when CONFIG_FW_LOADER is set. The mixartloader is necessary only
+ for older versions or when you build the driver into kernel.]
+
+For loading the firmware automatically after the module is loaded, use
+the post-install command. For example, add the following entry to
+/etc/modprobe.conf for miXart driver:
+
+ install snd-mixart /sbin/modprobe --first-time -i snd-mixart && \
+ /usr/bin/mixartloader
+(for 2.2/2.4 kernels, add "post-install snd-mixart /usr/bin/vxloader" to
+ /etc/modules.conf, instead.)
+
+The firmware binaries are installed on /usr/share/alsa/firmware
+(or /usr/local/share/alsa/firmware, depending to the prefix option of
+configure). There will be a miXart.conf file, which define the dsp image
+files.
+
+The firmware files are copyright by Digigram SA
+
+
+COPYRIGHT
+=========
+
+Copyright (c) 2003 Digigram SA <alsa@digigram.com>
+Distributable under GPL.
diff --git a/Documentation/sound/alsa/OSS-Emulation.txt b/Documentation/sound/alsa/OSS-Emulation.txt
new file mode 100644
index 0000000..022aaeb
--- /dev/null
+++ b/Documentation/sound/alsa/OSS-Emulation.txt
@@ -0,0 +1,305 @@
+ NOTES ON KERNEL OSS-EMULATION
+ =============================
+
+ Jan. 22, 2004 Takashi Iwai <tiwai@suse.de>
+
+
+Modules
+=======
+
+ALSA provides a powerful OSS emulation on the kernel.
+The OSS emulation for PCM, mixer and sequencer devices is implemented
+as add-on kernel modules, snd-pcm-oss, snd-mixer-oss and snd-seq-oss.
+When you need to access the OSS PCM, mixer or sequencer devices, the
+corresponding module has to be loaded.
+
+These modules are loaded automatically when the corresponding service
+is called. The alias is defined sound-service-x-y, where x and y are
+the card number and the minor unit number. Usually you don't have to
+define these aliases by yourself.
+
+Only necessary step for auto-loading of OSS modules is to define the
+card alias in /etc/modprobe.conf, such as
+
+ alias sound-slot-0 snd-emu10k1
+
+As the second card, define sound-slot-1 as well.
+Note that you can't use the aliased name as the target name (i.e.
+"alias sound-slot-0 snd-card-0" doesn't work any more like the old
+modutils).
+
+The currently available OSS configuration is shown in
+/proc/asound/oss/sndstat. This shows in the same syntax of
+/dev/sndstat, which is available on the commercial OSS driver.
+On ALSA, you can symlink /dev/sndstat to this proc file.
+
+Please note that the devices listed in this proc file appear only
+after the corresponding OSS-emulation module is loaded. Don't worry
+even if "NOT ENABLED IN CONFIG" is shown in it.
+
+
+Device Mapping
+==============
+
+ALSA supports the following OSS device files:
+
+ PCM:
+ /dev/dspX
+ /dev/adspX
+
+ Mixer:
+ /dev/mixerX
+
+ MIDI:
+ /dev/midi0X
+ /dev/amidi0X
+
+ Sequencer:
+ /dev/sequencer
+ /dev/sequencer2 (aka /dev/music)
+
+where X is the card number from 0 to 7.
+
+(NOTE: Some distributions have the device files like /dev/midi0 and
+ /dev/midi1. They are NOT for OSS but for tclmidi, which is
+ a totally different thing.)
+
+Unlike the real OSS, ALSA cannot use the device files more than the
+assigned ones. For example, the first card cannot use /dev/dsp1 or
+/dev/dsp2, but only /dev/dsp0 and /dev/adsp0.
+
+As seen above, PCM and MIDI may have two devices. Usually, the first
+PCM device (hw:0,0 in ALSA) is mapped to /dev/dsp and the secondary
+device (hw:0,1) to /dev/adsp (if available). For MIDI, /dev/midi and
+/dev/amidi, respectively.
+
+You can change this device mapping via the module options of
+snd-pcm-oss and snd-rawmidi. In the case of PCM, the following
+options are available for snd-pcm-oss:
+
+ dsp_map PCM device number assigned to /dev/dspX
+ (default = 0)
+ adsp_map PCM device number assigned to /dev/adspX
+ (default = 1)
+
+For example, to map the third PCM device (hw:0,2) to /dev/adsp0,
+define like this:
+
+ options snd-pcm-oss adsp_map=2
+
+The options take arrays. For configuring the second card, specify
+two entries separated by comma. For example, to map the third PCM
+device on the second card to /dev/adsp1, define like below:
+
+ options snd-pcm-oss adsp_map=0,2
+
+To change the mapping of MIDI devices, the following options are
+available for snd-rawmidi:
+
+ midi_map MIDI device number assigned to /dev/midi0X
+ (default = 0)
+ amidi_map MIDI device number assigned to /dev/amidi0X
+ (default = 1)
+
+For example, to assign the third MIDI device on the first card to
+/dev/midi00, define as follows:
+
+ options snd-rawmidi midi_map=2
+
+
+PCM Mode
+========
+
+As default, ALSA emulates the OSS PCM with so-called plugin layer,
+i.e. tries to convert the sample format, rate or channels
+automatically when the card doesn't support it natively.
+This will lead to some problems for some applications like quake or
+wine, especially if they use the card only in the MMAP mode.
+
+In such a case, you can change the behavior of PCM per application by
+writing a command to the proc file. There is a proc file for each PCM
+stream, /proc/asound/cardX/pcmY[cp]/oss, where X is the card number
+(zero-based), Y the PCM device number (zero-based), and 'p' is for
+playback and 'c' for capture, respectively. Note that this proc file
+exists only after snd-pcm-oss module is loaded.
+
+The command sequence has the following syntax:
+
+ app_name fragments fragment_size [options]
+
+app_name is the name of application with (higher priority) or without
+path.
+fragments specifies the number of fragments or zero if no specific
+number is given.
+fragment_size is the size of fragment in bytes or zero if not given.
+options is the optional parameters. The following options are
+available:
+
+ disable the application tries to open a pcm device for
+ this channel but does not want to use it.
+ direct don't use plugins
+ block force block open mode
+ non-block force non-block open mode
+ partial-frag write also partial fragments (affects playback only)
+ no-silence do not fill silence ahead to avoid clicks
+
+The disable option is useful when one stream direction (playback or
+capture) is not handled correctly by the application although the
+hardware itself does support both directions.
+The direct option is used, as mentioned above, to bypass the automatic
+conversion and useful for MMAP-applications.
+For example, to playback the first PCM device without plugins for
+quake, send a command via echo like the following:
+
+ % echo "quake 0 0 direct" > /proc/asound/card0/pcm0p/oss
+
+While quake wants only playback, you may append the second command
+to notify driver that only this direction is about to be allocated:
+
+ % echo "quake 0 0 disable" > /proc/asound/card0/pcm0c/oss
+
+The permission of proc files depend on the module options of snd.
+As default it's set as root, so you'll likely need to be superuser for
+sending the command above.
+
+The block and non-block options are used to change the behavior of
+opening the device file.
+
+As default, ALSA behaves as original OSS drivers, i.e. does not block
+the file when it's busy. The -EBUSY error is returned in this case.
+
+This blocking behavior can be changed globally via nonblock_open
+module option of snd-pcm-oss. For using the blocking mode as default
+for OSS devices, define like the following:
+
+ options snd-pcm-oss nonblock_open=0
+
+The partial-frag and no-silence commands have been added recently.
+Both commands are for optimization use only. The former command
+specifies to invoke the write transfer only when the whole fragment is
+filled. The latter stops writing the silence data ahead
+automatically. Both are disabled as default.
+
+You can check the currently defined configuration by reading the proc
+file. The read image can be sent to the proc file again, hence you
+can save the current configuration
+
+ % cat /proc/asound/card0/pcm0p/oss > /somewhere/oss-cfg
+
+and restore it like
+
+ % cat /somewhere/oss-cfg > /proc/asound/card0/pcm0p/oss
+
+Also, for clearing all the current configuration, send "erase" command
+as below:
+
+ % echo "erase" > /proc/asound/card0/pcm0p/oss
+
+
+Mixer Elements
+==============
+
+Since ALSA has completely different mixer interface, the emulation of
+OSS mixer is relatively complicated. ALSA builds up a mixer element
+from several different ALSA (mixer) controls based on the name
+string. For example, the volume element SOUND_MIXER_PCM is composed
+from "PCM Playback Volume" and "PCM Playback Switch" controls for the
+playback direction and from "PCM Capture Volume" and "PCM Capture
+Switch" for the capture directory (if exists). When the PCM volume of
+OSS is changed, all the volume and switch controls above are adjusted
+automatically.
+
+As default, ALSA uses the following control for OSS volumes:
+
+ OSS volume ALSA control Index
+ -----------------------------------------------------
+ SOUND_MIXER_VOLUME Master 0
+ SOUND_MIXER_BASS Tone Control - Bass 0
+ SOUND_MIXER_TREBLE Tone Control - Treble 0
+ SOUND_MIXER_SYNTH Synth 0
+ SOUND_MIXER_PCM PCM 0
+ SOUND_MIXER_SPEAKER PC Speaker 0
+ SOUND_MIXER_LINE Line 0
+ SOUND_MIXER_MIC Mic 0
+ SOUND_MIXER_CD CD 0
+ SOUND_MIXER_IMIX Monitor Mix 0
+ SOUND_MIXER_ALTPCM PCM 1
+ SOUND_MIXER_RECLEV (not assigned)
+ SOUND_MIXER_IGAIN Capture 0
+ SOUND_MIXER_OGAIN Playback 0
+ SOUND_MIXER_LINE1 Aux 0
+ SOUND_MIXER_LINE2 Aux 1
+ SOUND_MIXER_LINE3 Aux 2
+ SOUND_MIXER_DIGITAL1 Digital 0
+ SOUND_MIXER_DIGITAL2 Digital 1
+ SOUND_MIXER_DIGITAL3 Digital 2
+ SOUND_MIXER_PHONEIN Phone 0
+ SOUND_MIXER_PHONEOUT Phone 1
+ SOUND_MIXER_VIDEO Video 0
+ SOUND_MIXER_RADIO Radio 0
+ SOUND_MIXER_MONITOR Monitor 0
+
+The second column is the base-string of the corresponding ALSA
+control. In fact, the controls with "XXX [Playback|Capture]
+[Volume|Switch]" will be checked in addition.
+
+The current assignment of these mixer elements is listed in the proc
+file, /proc/asound/cardX/oss_mixer, which will be like the following
+
+ VOLUME "Master" 0
+ BASS "" 0
+ TREBLE "" 0
+ SYNTH "" 0
+ PCM "PCM" 0
+ ...
+
+where the first column is the OSS volume element, the second column
+the base-string of the corresponding ALSA control, and the third the
+control index. When the string is empty, it means that the
+corresponding OSS control is not available.
+
+For changing the assignment, you can write the configuration to this
+proc file. For example, to map "Wave Playback" to the PCM volume,
+send the command like the following:
+
+ % echo 'VOLUME "Wave Playback" 0' > /proc/asound/card0/oss_mixer
+
+The command is exactly as same as listed in the proc file. You can
+change one or more elements, one volume per line. In the last
+example, both "Wave Playback Volume" and "Wave Playback Switch" will
+be affected when PCM volume is changed.
+
+Like the case of PCM proc file, the permission of proc files depend on
+the module options of snd. you'll likely need to be superuser for
+sending the command above.
+
+As well as in the case of PCM proc file, you can save and restore the
+current mixer configuration by reading and writing the whole file
+image.
+
+
+Duplex Streams
+==============
+
+Note that when attempting to use a single device file for playback and
+capture, the OSS API provides no way to set the format, sample rate or
+number of channels different in each direction. Thus
+ io_handle = open("device", O_RDWR)
+will only function correctly if the values are the same in each direction.
+
+To use different values in the two directions, use both
+ input_handle = open("device", O_RDONLY)
+ output_handle = open("device", O_WRONLY)
+and set the values for the corresponding handle.
+
+
+Unsupported Features
+====================
+
+MMAP on ICE1712 driver
+----------------------
+ICE1712 supports only the unconventional format, interleaved
+10-channels 24bit (packed in 32bit) format. Therefore you cannot mmap
+the buffer as the conventional (mono or 2-channels, 8 or 16bit) format
+on OSS.
+
diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt
new file mode 100644
index 0000000..f738b29
--- /dev/null
+++ b/Documentation/sound/alsa/Procfile.txt
@@ -0,0 +1,207 @@
+ Proc Files of ALSA Drivers
+ ==========================
+ Takashi Iwai <tiwai@suse.de>
+
+General
+-------
+
+ALSA has its own proc tree, /proc/asound. Many useful information are
+found in this tree. When you encounter a problem and need debugging,
+check the files listed in the following sections.
+
+Each card has its subtree cardX, where X is from 0 to 7. The
+card-specific files are stored in the card* subdirectories.
+
+
+Global Information
+------------------
+
+cards
+ Shows the list of currently configured ALSA drivers,
+ index, the id string, short and long descriptions.
+
+version
+ Shows the version string and compile date.
+
+modules
+ Lists the module of each card
+
+devices
+ Lists the ALSA native device mappings.
+
+meminfo
+ Shows the status of allocated pages via ALSA drivers.
+ Appears only when CONFIG_SND_DEBUG=y.
+
+hwdep
+ Lists the currently available hwdep devices in format of
+ <card>-<device>: <name>
+
+pcm
+ Lists the currently available PCM devices in format of
+ <card>-<device>: <id>: <name> : <sub-streams>
+
+timer
+ Lists the currently available timer devices
+
+
+oss/devices
+ Lists the OSS device mappings.
+
+oss/sndstat
+ Provides the output compatible with /dev/sndstat.
+ You can symlink this to /dev/sndstat.
+
+
+Card Specific Files
+-------------------
+
+The card-specific files are found in /proc/asound/card* directories.
+Some drivers (e.g. cmipci) have their own proc entries for the
+register dump, etc (e.g. /proc/asound/card*/cmipci shows the register
+dump). These files would be really helpful for debugging.
+
+When PCM devices are available on this card, you can see directories
+like pcm0p or pcm1c. They hold the PCM information for each PCM
+stream. The number after 'pcm' is the PCM device number from 0, and
+the last 'p' or 'c' means playback or capture direction. The files in
+this subtree is described later.
+
+The status of MIDI I/O is found in midi* files. It shows the device
+name and the received/transmitted bytes through the MIDI device.
+
+When the card is equipped with AC97 codecs, there are codec97#*
+subdirectories (described later).
+
+When the OSS mixer emulation is enabled (and the module is loaded),
+oss_mixer file appears here, too. This shows the current mapping of
+OSS mixer elements to the ALSA control elements. You can change the
+mapping by writing to this device. Read OSS-Emulation.txt for
+details.
+
+
+PCM Proc Files
+--------------
+
+card*/pcm*/info
+ The general information of this PCM device: card #, device #,
+ substreams, etc.
+
+card*/pcm*/xrun_debug
+ This file appears when CONFIG_SND_DEBUG=y.
+ This shows the status of xrun (= buffer overrun/xrun) debug of
+ ALSA PCM middle layer, as an integer from 0 to 2. The value
+ can be changed by writing to this file, such as
+
+ # cat 2 > /proc/asound/card0/pcm0p/xrun_debug
+
+ When this value is greater than 0, the driver will show the
+ messages to kernel log when an xrun is detected. The debug
+ message is shown also when the invalid H/W pointer is detected
+ at the update of periods (usually called from the interrupt
+ handler).
+
+ When this value is greater than 1, the driver will show the
+ stack trace additionally. This may help the debugging.
+
+card*/pcm*/sub*/info
+ The general information of this PCM sub-stream.
+
+card*/pcm*/sub*/status
+ The current status of this PCM sub-stream, elapsed time,
+ H/W position, etc.
+
+card*/pcm*/sub*/hw_params
+ The hardware parameters set for this sub-stream.
+
+card*/pcm*/sub*/sw_params
+ The soft parameters set for this sub-stream.
+
+card*/pcm*/sub*/prealloc
+ The buffer pre-allocation information.
+
+
+AC97 Codec Information
+----------------------
+
+card*/codec97#*/ac97#?-?
+ Shows the general information of this AC97 codec chip, such as
+ name, capabilities, set up.
+
+card*/codec97#0/ac97#?-?+regs
+ Shows the AC97 register dump. Useful for debugging.
+
+ When CONFIG_SND_DEBUG is enabled, you can write to this file for
+ changing an AC97 register directly. Pass two hex numbers.
+ For example,
+
+ # echo 02 9f1f > /proc/asound/card0/codec97#0/ac97#0-0+regs
+
+
+USB Audio Streams
+-----------------
+
+card*/stream*
+ Shows the assignment and the current status of each audio stream
+ of the given card. This information is very useful for debugging.
+
+
+HD-Audio Codecs
+---------------
+
+card*/codec#*
+ Shows the general codec information and the attribute of each
+ widget node.
+
+
+Sequencer Information
+---------------------
+
+seq/drivers
+ Lists the currently available ALSA sequencer drivers.
+
+seq/clients
+ Shows the list of currently available sequencer clients and
+ ports. The connection status and the running status are shown
+ in this file, too.
+
+seq/queues
+ Lists the currently allocated/running sequencer queues.
+
+seq/timer
+ Lists the currently allocated/running sequencer timers.
+
+seq/oss
+ Lists the OSS-compatible sequencer stuffs.
+
+
+Help For Debugging?
+-------------------
+
+When the problem is related with PCM, first try to turn on xrun_debug
+mode. This will give you the kernel messages when and where xrun
+happened.
+
+If it's really a bug, report it with the following information:
+
+ - the name of the driver/card, show in /proc/asound/cards
+ - the register dump, if available (e.g. card*/cmipci)
+
+when it's a PCM problem,
+
+ - set-up of PCM, shown in hw_parms, sw_params, and status in the PCM
+ sub-stream directory
+
+when it's a mixer problem,
+
+ - AC97 proc files, codec97#*/* files
+
+for USB audio/midi,
+
+ - output of lsusb -v
+ - stream* files in card directory
+
+
+The ALSA bug-tracking system is found at:
+
+ https://bugtrack.alsa-project.org/alsa-bug/
diff --git a/Documentation/sound/alsa/SB-Live-mixer.txt b/Documentation/sound/alsa/SB-Live-mixer.txt
new file mode 100644
index 0000000..f5639d4
--- /dev/null
+++ b/Documentation/sound/alsa/SB-Live-mixer.txt
@@ -0,0 +1,356 @@
+
+ Sound Blaster Live mixer / default DSP code
+ ===========================================
+
+
+The EMU10K1 chips have a DSP part which can be programmed to support
+various ways of sample processing, which is described here.
+(This article does not deal with the overall functionality of the
+EMU10K1 chips. See the manuals section for further details.)
+
+The ALSA driver programs this portion of chip by default code
+(can be altered later) which offers the following functionality:
+
+
+1) IEC958 (S/PDIF) raw PCM
+--------------------------
+
+This PCM device (it's the 4th PCM device (index 3!) and first subdevice
+(index 0) for a given card) allows to forward 48kHz, stereo, 16-bit
+little endian streams without any modifications to the digital output
+(coaxial or optical). The universal interface allows the creation of up
+to 8 raw PCM devices operating at 48kHz, 16-bit little endian. It would
+be easy to add support for multichannel devices to the current code,
+but the conversion routines exist only for stereo (2-channel streams)
+at the time.
+
+Look to tram_poke routines in lowlevel/emu10k1/emufx.c for more details.
+
+
+2) 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
+here. Note that the controls work as attenuators: the maximum value is the
+neutral position leaving the signal unchanged. Note that if the same destination
+is mentioned in multiple controls, the signal is accumulated and can be wrapped
+(set to maximal or minimal value without checking of overflow).
+
+
+Explanation of used abbreviations:
+
+DAC - digital to analog converter
+ADC - analog to digital converter
+I2S - one-way three wire serial bus for digital sound by Philips Semiconductors
+ (this standard is used for connecting standalone DAC and ADC converters)
+LFE - low frequency effects (subwoofer signal)
+AC97 - a chip containing an analog mixer, DAC and ADC converters
+IEC958 - S/PDIF
+FX-bus - the EMU10K1 chip has an effect bus containing 16 accumulators.
+ Each of the synthesizer voices can feed its output to these accumulators
+ and the DSP microcontroller can operate with the resulting sum.
+
+
+name='Wave 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.
+The result samples are forwarded to the front DAC PCM slots of the AC97 codec.
+
+name='Wave Surround 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.
+The result samples are forwarded to the rear I2S DACs. These DACs operates
+separately (they are not inside the AC97 codec).
+
+name='Wave Center 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.
+The result is mixed to mono signal (single channel) and forwarded to
+the ??rear?? right DAC PCM slot of the AC97 codec.
+
+name='Wave LFE 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.
+The result is mixed to mono signal (single channel) and forwarded to
+the ??rear?? left DAC PCM slot of the AC97 codec.
+
+name='Wave Capture Volume',index=0
+name='Wave Capture Switch',index=0
+
+These controls are 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
+name='Music Capture Switch',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='Surround Playback Volume',index=0
+
+This control is used to attenuate samples for left and right rear PCM FX-bus
+accumulators. ALSA uses accumulators 2 and 3 for left and right rear PCM samples.
+The result samples are forwarded to the rear I2S DACs. These DACs operate
+separately (they are not inside the AC97 codec).
+
+name='Surround Capture Volume',index=0
+name='Surround Capture Switch',index=0
+
+These controls are used to attenuate samples for left and right rear PCM FX-bus
+accumulators. ALSA uses accumulators 2 and 3 for left and right rear PCM samples.
+The result is forwarded to the ADC capture FIFO (thus to the standard capture
+PCM device).
+
+name='Center Playback Volume',index=0
+
+This control is used to attenuate sample for center PCM FX-bus accumulator.
+ALSA uses accumulator 6 for center PCM sample. The result sample is forwarded
+to the ??rear?? right DAC PCM slot of the AC97 codec.
+
+name='LFE Playback Volume',index=0
+
+This control is used to attenuate sample for center PCM FX-bus accumulator.
+ALSA uses accumulator 6 for center PCM sample. The result sample is forwarded
+to the ??rear?? left DAC PCM slot of the AC97 codec.
+
+name='AC97 Playback Volume',index=0
+
+This control is used to attenuate samples for left and right front ADC PCM slots
+of the AC97 codec. The result samples are forwarded to the front DAC PCM
+slots of the AC97 codec.
+********************************************************************************
+*** Note: This control should be zero for the standard operations, otherwise ***
+*** a digital loopback is activated. ***
+********************************************************************************
+
+name='AC97 Capture Volume',index=0
+
+This control is used to attenuate samples for left and right front ADC PCM slots
+of the AC97 codec. The result is forwarded to the ADC capture FIFO (thus to
+the standard capture PCM device).
+********************************************************************************
+*** Note: This control should be 100 (maximal value), otherwise no analog ***
+*** inputs of the AC97 codec can be captured (recorded). ***
+********************************************************************************
+
+name='IEC958 TTL 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 AC97 codec.
+
+name='IEC958 TTL 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='Zoom Video Playback Volume',index=0
+
+This control is used to attenuate samples from left and right zoom video
+digital inputs (usually used by a CDROM drive). The result samples are
+forwarded to the front DAC PCM slots of the AC97 codec.
+
+name='Zoom Video Capture Volume',index=0
+
+This control is used to attenuate samples from left and right zoom video
+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 LiveDrive 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 AC97 codec.
+
+name='IEC958 LiveDrive 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='IEC958 Coaxial Playback Volume',index=0
+
+This control is used to attenuate samples from left and right IEC958 coaxial
+digital inputs. The result samples are forwarded to the front DAC PCM slots
+of the AC97 codec.
+
+name='IEC958 Coaxial Capture Volume',index=0
+
+This control is used to attenuate samples from left and right IEC958 coaxial
+digital inputs. The result samples are forwarded to the ADC capture FIFO
+(thus to the standard capture PCM device).
+
+name='Line LiveDrive Playback Volume',index=0
+name='Line LiveDrive Playback Volume',index=1
+
+This control is used to attenuate samples from left and right I2S ADC
+inputs (on the LiveDrive). The result samples are forwarded to the front
+DAC PCM slots of the AC97 codec.
+
+name='Line LiveDrive Capture Volume',index=1
+name='Line LiveDrive Capture Volume',index=1
+
+This control is used to attenuate samples from left and right I2S ADC
+inputs (on the LiveDrive). The result samples are forwarded to the ADC
+capture FIFO (thus to the standard capture PCM device).
+
+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='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.
+
+name='Headphone Playback Volume',index=1
+
+This control attenuates the samples for the headphone output.
+
+name='Headphone Center Playback Switch',index=1
+
+If this switch is on, then the sample for the center PCM is put to the
+left headphone output (useful for SB Live cards without separate center/LFE
+output).
+
+name='Headphone LFE Playback Switch',index=1
+
+If this switch is on, then the sample for the center PCM is put to the
+right headphone output (useful for SB Live cards without separate center/LFE
+output).
+
+
+3) 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)
+ 1 - left, 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 are
+twelve values with this mapping:
+
+ 0 - mono, A destination (FX-bus 0-15), default 0
+ 1 - mono, B destination (FX-bus 0-15), default 1
+ 2 - mono, C destination (FX-bus 0-15), default 2
+ 3 - mono, D destination (FX-bus 0-15), default 3
+ 4 - left, A destination (FX-bus 0-15), default 0
+ 5 - left, B destination (FX-bus 0-15), default 1
+ 6 - left, C destination (FX-bus 0-15), default 2
+ 7 - left, D destination (FX-bus 0-15), default 3
+ 8 - right, A destination (FX-bus 0-15), default 0
+ 9 - right, B destination (FX-bus 0-15), default 1
+ 10 - right, C destination (FX-bus 0-15), default 2
+ 11 - right, D destination (FX-bus 0-15), default 3
+
+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)
+ 1 - mono, B destination attn, default 255 (no attenuation)
+ 2 - mono, C destination attn, default 0 (mute)
+ 3 - mono, D destination attn, default 0 (mute)
+ 4 - left, A destination attn, default 255 (no attenuation)
+ 5 - left, B destination attn, default 0 (mute)
+ 6 - left, C destination attn, default 0 (mute)
+ 7 - left, D destination attn, default 0 (mute)
+ 8 - right, A destination attn, default 0 (mute)
+ 9 - right, B destination attn, default 255 (no attenuation)
+ 10 - right, C destination attn, default 0 (mute)
+ 11 - right, D destination attn, default 0 (mute)
+
+
+
+4) MANUALS/PATENTS:
+-------------------
+
+ftp://opensource.creative.com/pub/doc
+-------------------------------------
+
+ Files:
+ LM4545.pdf AC97 Codec
+
+ m2049.pdf The EMU10K1 Digital Audio Processor
+
+ 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 9901953 (A1) 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 5928342 Audio Effects Processor integrated on a single chip (Jul. 27, 1999)
+ with a multiport memory onto which multiple asynchronous
+ digital sound samples can be concurrently loaded
+
+ US 5930158 Processor with Instruction Set for Audio Effects (Jul. 27, 1999)
+
+ US 6032235 Memory initialization circuit (Tram) (Feb. 29, 2000)
+
+ US 6138207 Interpolation looping of audio samples in cache connected to (Oct. 24, 2000)
+ system bus with prioritization and modification of bus transfers
+ in accordance with loop ends and minimum block sizes
+
+ US 6151670 Method for conserving memory storage using a (Nov. 21, 2000)
+ pool of short term memory registers
+
+ US 6195715 Interrupt control for multiple programs communicating with (Feb. 27, 2001)
+ a common interrupt by associating programs to GP registers,
+ defining interrupt register, polling GP registers, and invoking
+ callback routine associated with defined interrupt register
diff --git a/Documentation/sound/alsa/VIA82xx-mixer.txt b/Documentation/sound/alsa/VIA82xx-mixer.txt
new file mode 100644
index 0000000..1b0ac06
--- /dev/null
+++ b/Documentation/sound/alsa/VIA82xx-mixer.txt
@@ -0,0 +1,8 @@
+
+ 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.
diff --git a/Documentation/sound/alsa/emu10k1-jack.txt b/Documentation/sound/alsa/emu10k1-jack.txt
new file mode 100644
index 0000000..751d450
--- /dev/null
+++ b/Documentation/sound/alsa/emu10k1-jack.txt
@@ -0,0 +1,74 @@
+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
+by the kX Project. Without their work I never would have discovered the true
+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
+Windows driver. As of ALSA 1.0.9 this is no more!
+
+For those unfamiliar with kX ASIO, this consists of 16 capture and 16 playback
+channels. With a post 2.6.9 Linux kernel, latencies down to 64 (1.33 ms) or
+even 32 (0.66ms) frames should work well.
+
+The configuration is slightly more involved than on Windows, as you have to
+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
+
+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).
+
+The 16 input ports are connected to the 16 physical inputs. Contrary to
+popular belief, all emu10k1 cards are multichannel cards. Which of these
+input channels have physical inputs connected to them depends on the card
+model. Trial and error is highly recommended; the pinout diagrams
+for the card have been reverse engineered by some enterprising kX users and are
+available on the internet. Meterbridge is helpful here, and the kX forums are
+packed with useful information.
+
+Each input port will either correspond to a digital (SPDIF) input, an analog
+input, or nothing. The one exception is the SBLive! 5.1. On these devices,
+the second and third input ports are wired to the center/LFE output. You will
+still see 16 capture channels, but only 14 are available for recording inputs.
+
+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 Epilog FXBUS2(nr)
+--------------------------------------------
+capture_1 asio14 FXBUS2(0xe)
+capture_2 asio15 FXBUS2(0xf)
+capture_3 asio0 FXBUS2(0x0)
+~capture_4 Center EXTOUT(0x11) // mapped to by Center
+~capture_5 LFE EXTOUT(0x12) // mapped to by LFE
+capture_6 asio3 FXBUS2(0x3)
+capture_7 asio4 FXBUS2(0x4)
+capture_8 asio5 FXBUS2(0x5)
+capture_9 asio6 FXBUS2(0x6)
+capture_10 asio7 FXBUS2(0x7)
+capture_11 asio8 FXBUS2(0x8)
+capture_12 asio9 FXBUS2(0x9)
+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
diff --git a/Documentation/sound/alsa/hda_codec.txt b/Documentation/sound/alsa/hda_codec.txt
new file mode 100644
index 0000000..34e87ec
--- /dev/null
+++ b/Documentation/sound/alsa/hda_codec.txt
@@ -0,0 +1,322 @@
+Notes on Universal Interface for Intel High Definition Audio Codec
+------------------------------------------------------------------
+
+Takashi Iwai <tiwai@suse.de>
+
+
+[Still a draft version]
+
+
+General
+=======
+
+The snd-hda-codec module supports the generic access function for the
+High Definition (HD) audio codecs. It's designed to be independent
+from the controller code like ac97 codec module. The real accessors
+from/to the controller must be implemented in the lowlevel driver.
+
+The structure of this module is similar with ac97_codec module.
+Each codec chip belongs to a bus class which communicates with the
+controller.
+
+
+Initialization of Bus Instance
+==============================
+
+The card driver has to create struct hda_bus at first. The template
+struct should be filled and passed to the constructor:
+
+struct hda_bus_template {
+ void *private_data;
+ struct pci_dev *pci;
+ const char *modelname;
+ struct hda_bus_ops ops;
+};
+
+The card driver can set and use the private_data field to retrieve its
+own data in callback functions. The pci field is used when the patch
+needs to check the PCI subsystem IDs, so on. For non-PCI system, it
+doesn't have to be set, of course.
+The modelname field specifies the board's specific configuration. The
+string is passed to the codec parser, and it depends on the parser how
+the string is used.
+These fields, private_data, pci and modelname are all optional.
+
+The ops field contains the callback functions as the following:
+
+struct hda_bus_ops {
+ int (*command)(struct hda_codec *codec, hda_nid_t nid, int direct,
+ unsigned int verb, unsigned int parm);
+ unsigned int (*get_response)(struct hda_codec *codec);
+ void (*private_free)(struct hda_bus *);
+#ifdef CONFIG_SND_HDA_POWER_SAVE
+ void (*pm_notify)(struct hda_codec *codec);
+#endif
+};
+
+The command callback is called when the codec module needs to send a
+VERB to the controller. It's always a single command.
+The get_response callback is called when the codec requires the answer
+for the last command. These two callbacks are mandatory and have to
+be given.
+The third, private_free callback, is optional. It's called in the
+destructor to release any necessary data in the lowlevel driver.
+
+The pm_notify callback is available only with
+CONFIG_SND_HDA_POWER_SAVE kconfig. It's called when the codec needs
+to power up or may power down. The controller should check the all
+belonging codecs on the bus whether they are actually powered off
+(check codec->power_on), and optionally the driver may power down the
+controller side, too.
+
+The bus instance is created via snd_hda_bus_new(). You need to pass
+the card instance, the template, and the pointer to store the
+resultant bus instance.
+
+int snd_hda_bus_new(struct snd_card *card, const struct hda_bus_template *temp,
+ struct hda_bus **busp);
+
+It returns zero if successful. A negative return value means any
+error during creation.
+
+
+Creation of Codec Instance
+==========================
+
+Each codec chip on the board is then created on the BUS instance.
+To create a codec instance, call snd_hda_codec_new().
+
+int snd_hda_codec_new(struct hda_bus *bus, unsigned int codec_addr,
+ struct hda_codec **codecp);
+
+The first argument is the BUS instance, the second argument is the
+address of the codec, and the last one is the pointer to store the
+resultant codec instance (can be NULL if not needed).
+
+The codec is stored in a linked list of bus instance. You can follow
+the codec list like:
+
+ struct hda_codec *codec;
+ list_for_each_entry(codec, &bus->codec_list, list) {
+ ...
+ }
+
+The codec isn't initialized at this stage properly. The
+initialization sequence is called when the controls are built later.
+
+
+Codec Access
+============
+
+To access codec, use snd_hda_codec_read() and snd_hda_codec_write().
+snd_hda_param_read() is for reading parameters.
+For writing a sequence of verbs, use snd_hda_sequence_write().
+
+There are variants of cached read/write, snd_hda_codec_write_cache(),
+snd_hda_sequence_write_cache(). These are used for recording the
+register states for the power-mangement resume. When no PM is needed,
+these are equivalent with non-cached version.
+
+To retrieve the number of sub nodes connected to the given node, use
+snd_hda_get_sub_nodes(). The connection list can be obtained via
+snd_hda_get_connections() call.
+
+When an unsolicited event happens, pass the event via
+snd_hda_queue_unsol_event() so that the codec routines will process it
+later.
+
+
+(Mixer) Controls
+================
+
+To create mixer controls of all codecs, call
+snd_hda_build_controls(). It then builds the mixers and does
+initialization stuff on each codec.
+
+
+PCM Stuff
+=========
+
+snd_hda_build_pcms() gives the necessary information to create PCM
+streams. When it's called, each codec belonging to the bus stores
+codec->num_pcms and codec->pcm_info fields. The num_pcms indicates
+the number of elements in pcm_info array. The card driver is supposed
+to traverse the codec linked list, read the pcm information in
+pcm_info array, and build pcm instances according to them.
+
+The pcm_info array contains the following record:
+
+/* PCM information for each substream */
+struct hda_pcm_stream {
+ unsigned int substreams; /* number of substreams, 0 = not exist */
+ unsigned int channels_min; /* min. number of channels */
+ unsigned int channels_max; /* max. number of channels */
+ hda_nid_t nid; /* default NID to query rates/formats/bps, or set up */
+ u32 rates; /* supported rates */
+ u64 formats; /* supported formats (SNDRV_PCM_FMTBIT_) */
+ unsigned int maxbps; /* supported max. bit per sample */
+ struct hda_pcm_ops ops;
+};
+
+/* for PCM creation */
+struct hda_pcm {
+ char *name;
+ struct hda_pcm_stream stream[2];
+};
+
+The name can be passed to snd_pcm_new(). The stream field contains
+the information for playback (SNDRV_PCM_STREAM_PLAYBACK = 0) and
+capture (SNDRV_PCM_STREAM_CAPTURE = 1) directions. The card driver
+should pass substreams to snd_pcm_new() for the number of substreams
+to create.
+
+The channels_min, channels_max, rates and formats should be copied to
+runtime->hw record. They and maxbps fields are used also to compute
+the format value for the HDA codec and controller. Call
+snd_hda_calc_stream_format() to get the format value.
+
+The ops field contains the following callback functions:
+
+struct hda_pcm_ops {
+ int (*open)(struct hda_pcm_stream *info, struct hda_codec *codec,
+ struct snd_pcm_substream *substream);
+ int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec,
+ struct snd_pcm_substream *substream);
+ int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec,
+ unsigned int stream_tag, unsigned int format,
+ struct snd_pcm_substream *substream);
+ int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec,
+ struct snd_pcm_substream *substream);
+};
+
+All are non-NULL, so you can call them safely without NULL check.
+
+The open callback should be called in PCM open after runtime->hw is
+set up. It may override some setting and constraints additionally.
+Similarly, the close callback should be called in the PCM close.
+
+The prepare callback should be called in PCM prepare. This will set
+up the codec chip properly for the operation. The cleanup should be
+called in hw_free to clean up the configuration.
+
+The caller should check the return value, at least for open and
+prepare callbacks. When a negative value is returned, some error
+occurred.
+
+
+Proc Files
+==========
+
+Each codec dumps the widget node information in
+/proc/asound/card*/codec#* file. This information would be really
+helpful for debugging. Please provide its contents together with the
+bug report.
+
+
+Power Management
+================
+
+It's simple:
+Call snd_hda_suspend() in the PM suspend callback.
+Call snd_hda_resume() in the PM resume callback.
+
+
+Codec Preset (Patch)
+====================
+
+To set up and handle the codec functionality fully, each codec may
+have a codec preset (patch). It's defined in struct hda_codec_preset:
+
+ struct hda_codec_preset {
+ unsigned int id;
+ unsigned int mask;
+ unsigned int subs;
+ unsigned int subs_mask;
+ unsigned int rev;
+ const char *name;
+ int (*patch)(struct hda_codec *codec);
+ };
+
+When the codec id and codec subsystem id match with the given id and
+subs fields bitwise (with bitmask mask and subs_mask), the callback
+patch is called. The patch callback should initialize the codec and
+set the codec->patch_ops field. This is defined as below:
+
+ struct hda_codec_ops {
+ int (*build_controls)(struct hda_codec *codec);
+ int (*build_pcms)(struct hda_codec *codec);
+ int (*init)(struct hda_codec *codec);
+ void (*free)(struct hda_codec *codec);
+ void (*unsol_event)(struct hda_codec *codec, unsigned int res);
+ #ifdef CONFIG_PM
+ int (*suspend)(struct hda_codec *codec, pm_message_t state);
+ int (*resume)(struct hda_codec *codec);
+ #endif
+ #ifdef CONFIG_SND_HDA_POWER_SAVE
+ int (*check_power_status)(struct hda_codec *codec,
+ hda_nid_t nid);
+ #endif
+ };
+
+The build_controls callback is called from snd_hda_build_controls().
+Similarly, the build_pcms callback is called from
+snd_hda_build_pcms(). The init callback is called after
+build_controls to initialize the hardware.
+The free callback is called as a destructor.
+
+The unsol_event callback is called when an unsolicited event is
+received.
+
+The suspend and resume callbacks are for power management.
+They can be NULL if no special sequence is required. When the resume
+callback is NULL, the driver calls the init callback and resumes the
+registers from the cache. If other handling is needed, you'd need to
+write your own resume callback. There, the amp values can be resumed
+via
+ void snd_hda_codec_resume_amp(struct hda_codec *codec);
+and the other codec registers via
+ void snd_hda_codec_resume_cache(struct hda_codec *codec);
+
+The check_power_status callback is called when the amp value of the
+given widget NID is changed. The codec code can turn on/off the power
+appropriately from this information.
+
+Each entry can be NULL if not necessary to be called.
+
+
+Generic Parser
+==============
+
+When the device doesn't match with any given presets, the widgets are
+parsed via th generic parser (hda_generic.c). Its support is
+limited: no multi-channel support, for example.
+
+
+Digital I/O
+===========
+
+Call snd_hda_create_spdif_out_ctls() from the patch to create controls
+related with SPDIF out.
+
+
+Helper Functions
+================
+
+snd_hda_get_codec_name() stores the codec name on the given string.
+
+snd_hda_check_board_config() can be used to obtain the configuration
+information matching with the device. Define the model string table
+and the table with struct snd_pci_quirk entries (zero-terminated),
+and pass it to the function. The function checks the modelname given
+as a module parameter, and PCI subsystem IDs. If the matching entry
+is found, it returns the config field value.
+
+snd_hda_add_new_ctls() can be used to create and add control entries.
+Pass the zero-terminated array of struct snd_kcontrol_new
+
+Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be
+used for the entry of struct snd_kcontrol_new.
+
+The input MUX helper callbacks for such a control are provided, too:
+snd_hda_input_mux_info() and snd_hda_input_mux_put(). See
+patch_realtek.c for example.
diff --git a/Documentation/sound/alsa/hdspm.txt b/Documentation/sound/alsa/hdspm.txt
new file mode 100644
index 0000000..7a67ff7
--- /dev/null
+++ b/Documentation/sound/alsa/hdspm.txt
@@ -0,0 +1,362 @@
+Software Interface ALSA-DSP MADI Driver
+
+(translated from German, so no good English ;-),
+2004 - winfried ritsch
+
+
+
+ Full functionality has been added to the driver. Since some of
+ the Controls and startup-options are ALSA-Standard and only the
+ special Controls are described and discussed below.
+
+
+ hardware functionality:
+
+
+ Audio transmission:
+
+ number of channels -- depends on transmission mode
+
+ The number of channels chosen is from 1..Nmax. The reason to
+ use for a lower number of channels is only resource allocation,
+ since unused DMA channels are disabled and less memory is
+ allocated. So also the throughput of the PCI system can be
+ scaled. (Only important for low performance boards).
+
+ Single Speed -- 1..64 channels
+
+ (Note: Choosing the 56channel mode for transmission or as
+ receiver, only 56 are transmitted/received over the MADI, but
+ all 64 channels are available for the mixer, so channel count
+ for the driver)
+
+ Double Speed -- 1..32 channels
+
+ Note: Choosing the 56-channel mode for
+ transmission/receive-mode , only 28 are transmitted/received
+ over the MADI, but all 32 channels are available for the mixer,
+ so channel count for the driver
+
+
+ Quad Speed -- 1..16 channels
+
+ Note: Choosing the 56-channel mode for
+ transmission/receive-mode , only 14 are transmitted/received
+ over the MADI, but all 16 channels are available for the mixer,
+ so channel count for the driver
+
+ Format -- signed 32 Bit Little Endian (SNDRV_PCM_FMTBIT_S32_LE)
+
+ Sample Rates --
+
+ Single Speed -- 32000, 44100, 48000
+
+ Double Speed -- 64000, 88200, 96000 (untested)
+
+ Quad Speed -- 128000, 176400, 192000 (untested)
+
+ access-mode -- MMAP (memory mapped), Not interleaved
+ (PCM_NON-INTERLEAVED)
+
+ buffer-sizes -- 64,128,256,512,1024,2048,8192 Samples
+
+ fragments -- 2
+
+ Hardware-pointer -- 2 Modi
+
+
+ The Card supports the readout of the actual Buffer-pointer,
+ where DMA reads/writes. Since of the bulk mode of PCI it is only
+ 64 Byte accurate. SO it is not really usable for the
+ ALSA-mid-level functions (here the buffer-ID gives a better
+ result), but if MMAP is used by the application. Therefore it
+ can be configured at load-time with the parameter
+ precise-pointer.
+
+
+ (Hint: Experimenting I found that the pointer is maximum 64 to
+ large never to small. So if you subtract 64 you always have a
+ safe pointer for writing, which is used on this mode inside
+ ALSA. In theory now you can get now a latency as low as 16
+ Samples, which is a quarter of the interrupt possibilities.)
+
+ Precise Pointer -- off
+ interrupt used for pointer-calculation
+
+ Precise Pointer -- on
+ hardware pointer used.
+
+ Controller:
+
+
+ Since DSP-MADI-Mixer has 8152 Fader, it does not make sense to
+ use the standard mixer-controls, since this would break most of
+ (especially graphic) ALSA-Mixer GUIs. So Mixer control has be
+ provided by a 2-dimensional controller using the
+ hwdep-interface.
+
+ Also all 128+256 Peak and RMS-Meter can be accessed via the
+ hwdep-interface. Since it could be a performance problem always
+ copying and converting Peak and RMS-Levels even if you just need
+ one, I decided to export the hardware structure, so that of
+ needed some driver-guru can implement a memory-mapping of mixer
+ or peak-meters over ioctl, or also to do only copying and no
+ conversion. A test-application shows the usage of the controller.
+
+ Latency Controls --- not implemented !!!
+
+
+ Note: Within the windows-driver the latency is accessible of a
+ control-panel, but buffer-sizes are controlled with ALSA from
+ hwparams-calls and should not be changed in run-state, I did not
+ implement it here.
+
+
+ System Clock -- suspended !!!!
+
+ Name -- "System Clock Mode"
+
+ Access -- Read Write
+
+ Values -- "Master" "Slave"
+
+
+ !!!! This is a hardware-function but is in conflict with the
+ Clock-source controller, which is a kind of ALSA-standard. I
+ makes sense to set the card to a special mode (master at some
+ frequency or slave), since even not using an Audio-application
+ a studio should have working synchronisations setup. So use
+ Clock-source-controller instead !!!!
+
+ Clock Source
+
+ Name -- "Sample Clock Source"
+
+ Access -- Read Write
+
+ Values -- "AutoSync", "Internal 32.0 kHz", "Internal 44.1 kHz",
+ "Internal 48.0 kHz", "Internal 64.0 kHz", "Internal 88.2 kHz",
+ "Internal 96.0 kHz"
+
+ Choose between Master at a specific Frequency and so also the
+ Speed-mode or Slave (Autosync). Also see "Preferred Sync Ref"
+
+
+ !!!! This is no pure hardware function but was implemented by
+ ALSA by some ALSA-drivers before, so I use it also. !!!
+
+
+ Preferred Sync Ref
+
+ Name -- "Preferred Sync Reference"
+
+ Access -- Read Write
+
+ Values -- "Word" "MADI"
+
+
+ Within the Auto-sync-Mode the preferred Sync Source can be
+ chosen. If it is not available another is used if possible.
+
+ Note: Since MADI has a much higher bit-rate than word-clock, the
+ card should synchronise better in MADI Mode. But since the
+ RME-PLL is very good, there are almost no problems with
+ word-clock too. I never found a difference.
+
+
+ TX 64 channel ---
+
+ Name -- "TX 64 channels mode"
+
+ Access -- Read Write
+
+ Values -- 0 1
+
+ Using 64-channel-modus (1) or 56-channel-modus for
+ MADI-transmission (0).
+
+
+ Note: This control is for output only. Input-mode is detected
+ automatically from hardware sending MADI.
+
+
+ Clear TMS ---
+
+ Name -- "Clear Track Marker"
+
+ Access -- Read Write
+
+ Values -- 0 1
+
+
+ Don't use to lower 5 Audio-bits on AES as additional Bits.
+
+
+ Safe Mode oder Auto Input ---
+
+ Name -- "Safe Mode"
+
+ Access -- Read Write
+
+ Values -- 0 1
+
+ (default on)
+
+ If on (1), then if either the optical or coaxial connection
+ has a failure, there is a takeover to the working one, with no
+ sample failure. Its only useful if you use the second as a
+ backup connection.
+
+ Input ---
+
+ Name -- "Input Select"
+
+ Access -- Read Write
+
+ Values -- optical coaxial
+
+
+ Choosing the Input, optical or coaxial. If Safe-mode is active,
+ this is the preferred Input.
+
+-------------- Mixer ----------------------
+
+ Mixer
+
+ Name -- "Mixer"
+
+ Access -- Read Write
+
+ Values - <channel-number 0-127> <Value 0-65535>
+
+
+ Here as a first value the channel-index is taken to get/set the
+ corresponding mixer channel, where 0-63 are the input to output
+ fader and 64-127 the playback to outputs fader. Value 0
+ is channel muted 0 and 32768 an amplification of 1.
+
+ Chn 1-64
+
+ fast mixer for the ALSA-mixer utils. The diagonal of the
+ mixer-matrix is implemented from playback to output.
+
+
+ Line Out
+
+ Name -- "Line Out"
+
+ Access -- Read Write
+
+ Values -- 0 1
+
+ Switching on and off the analog out, which has nothing to do
+ with mixing or routing. the analog outs reflects channel 63,64.
+
+
+--- information (only read access):
+
+ Sample Rate
+
+ Name -- "System Sample Rate"
+
+ Access -- Read-only
+
+ getting the sample rate.
+
+
+ External Rate measured
+
+ Name -- "External Rate"
+
+ Access -- Read only
+
+
+ Should be "Autosync Rate", but Name used is
+ ALSA-Scheme. External Sample frequency liked used on Autosync is
+ reported.
+
+
+ MADI Sync Status
+
+ Name -- "MADI Sync Lock Status"
+
+ Access -- Read
+
+ Values -- 0,1,2
+
+ MADI-Input is 0=Unlocked, 1=Locked, or 2=Synced.
+
+
+ Word Clock Sync Status
+
+ Name -- "Word Clock Lock Status"
+
+ Access -- Read
+
+ Values -- 0,1,2
+
+ Word Clock Input is 0=Unlocked, 1=Locked, or 2=Synced.
+
+ AutoSync
+
+ Name -- "AutoSync Reference"
+
+ Access -- Read
+
+ Values -- "WordClock", "MADI", "None"
+
+ Sync-Reference is either "WordClock", "MADI" or none.
+
+ RX 64ch --- noch nicht implementiert
+
+ MADI-Receiver is in 64 channel mode oder 56 channel mode.
+
+
+ AB_inp --- not tested
+
+ Used input for Auto-Input.
+
+
+ actual Buffer Position --- not implemented
+
+ !!! this is a ALSA internal function, so no control is used !!!
+
+
+
+Calling Parameter:
+
+ index int array (min = 1, max = 8),
+ "Index value for RME HDSPM interface." card-index within ALSA
+
+ note: ALSA-standard
+
+ id string array (min = 1, max = 8),
+ "ID string for RME HDSPM interface."
+
+ note: ALSA-standard
+
+ enable int array (min = 1, max = 8),
+ "Enable/disable specific HDSPM sound-cards."
+
+ note: ALSA-standard
+
+ precise_ptr int array (min = 1, max = 8),
+ "Enable precise pointer, or disable."
+
+ note: Use only when the application supports this (which is a special case).
+
+ line_outs_monitor int array (min = 1, max = 8),
+ "Send playback streams to analog outs by default."
+
+
+ note: each playback channel is mixed to the same numbered output
+ channel (routed). This is against the ALSA-convention, where all
+ channels have to be muted on after loading the driver, but was
+ used before on other cards, so i historically use it again)
+
+
+
+ enable_monitor int array (min = 1, max = 8),
+ "Enable Analog Out on Channel 63/64 by default."
+
+ note: here the analog output is enabled (but not routed). \ No newline at end of file
diff --git a/Documentation/sound/alsa/powersave.txt b/Documentation/sound/alsa/powersave.txt
new file mode 100644
index 0000000..9657e80
--- /dev/null
+++ b/Documentation/sound/alsa/powersave.txt
@@ -0,0 +1,41 @@
+Notes on Power-Saving Mode
+==========================
+
+AC97 and HD-audio drivers have the automatic power-saving mode.
+This feature is enabled via Kconfig CONFIG_SND_AC97_POWER_SAVE
+and CONFIG_SND_HDA_POWER_SAVE options, respectively.
+
+With the automatic power-saving, the driver turns off the codec power
+appropriately when no operation is required. When no applications use
+the device and/or no analog loopback is set, the power disablement is
+done fully or partially. It'll save a certain power consumption, thus
+good for laptops (even for desktops).
+
+The time-out for automatic power-off can be specified via power_save
+module option of snd-ac97-codec and snd-hda-intel modules. Specify
+the time-out value in seconds. 0 means to disable the automatic
+power-saving. The default value of timeout is given via
+CONFIG_SND_AC97_POWER_SAVE_DEFAULT and
+CONFIG_SND_HDA_POWER_SAVE_DEFAULT Kconfig options. Setting this to 1
+(the minimum value) isn't recommended because many applications try to
+reopen the device frequently. 10 would be a good choice for normal
+operations.
+
+The power_save option is exported as writable. This means you can
+adjust the value via sysfs on the fly. For example, to turn on the
+automatic power-save mode with 10 seconds, write to
+/sys/modules/snd_ac97_codec/parameters/power_save (usually as root):
+
+ # echo 10 > /sys/modules/snd_ac97_codec/parameters/power_save
+
+
+Note that you might hear click noise/pop when changing the power
+state. Also, it often takes certain time to wake up from the
+power-down to the active state. These are often hardly to fix, so
+don't report extra bug reports unless you have a fix patch ;-)
+
+For HD-audio interface, there is another module option,
+power_save_controller. This enables/disables the power-save mode of
+the controller side. Setting this on may reduce a bit more power
+consumption, but might result in longer wake-up time and click noise.
+Try to turn it off when you experience such a thing too often.
diff --git a/Documentation/sound/alsa/seq_oss.html b/Documentation/sound/alsa/seq_oss.html
new file mode 100644
index 0000000..d9776cf
--- /dev/null
+++ b/Documentation/sound/alsa/seq_oss.html
@@ -0,0 +1,409 @@
+<!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
+applicaion. 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>
diff --git a/Documentation/sound/alsa/serial-u16550.txt b/Documentation/sound/alsa/serial-u16550.txt
new file mode 100644
index 0000000..c191955
--- /dev/null
+++ b/Documentation/sound/alsa/serial-u16550.txt
@@ -0,0 +1,88 @@
+
+ Serial UART 16450/16550 MIDI driver
+ ===================================
+
+The adaptor module parameter allows you to select either:
+
+ 0 - Roland Soundcanvas support (default)
+ 1 - Midiator MS-124T support (1)
+ 2 - Midiator MS-124W S/A mode (2)
+ 3 - MS-124W M/B mode support (3)
+ 4 - Generic device with multiple input support (4)
+
+For the Midiator MS-124W, you must set the physical M-S and A-B
+switches on the Midiator to match the driver mode you select.
+
+In Roland Soundcanvas mode, multiple ALSA raw MIDI substreams are supported
+(midiCnD0-midiCnD15). Whenever you write to a different substream, the driver
+sends the nonstandard MIDI command sequence F5 NN, where NN is the substream
+number plus 1. Roland modules use this command to switch between different
+"parts", so this feature lets you treat each part as a distinct raw MIDI
+substream. The driver provides no way to send F5 00 (no selection) or to not
+send the F5 NN command sequence at all; perhaps it ought to.
+
+Usage example for simple serial converter:
+
+ /sbin/setserial /dev/ttyS0 uart none
+ /sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 speed=115200
+
+Usage example for Roland SoundCanvas with 4 MIDI ports:
+
+ /sbin/setserial /dev/ttyS0 uart none
+ /sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 outs=4
+
+In MS-124T mode, one raw MIDI substream is supported (midiCnD0); the outs
+module parameter is automatically set to 1. The driver sends the same data to
+all four MIDI Out connectors. Set the A-B switch and the speed module
+parameter to match (A=19200, B=9600).
+
+Usage example for MS-124T, with A-B switch in A position:
+
+ /sbin/setserial /dev/ttyS0 uart none
+ /sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 adaptor=1 \
+ speed=19200
+
+In MS-124W S/A mode, one raw MIDI substream is supported (midiCnD0);
+the outs module parameter is automatically set to 1. The driver sends
+the same data to all four MIDI Out connectors at full MIDI speed.
+
+Usage example for S/A mode:
+
+ /sbin/setserial /dev/ttyS0 uart none
+ /sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 adaptor=2
+
+In MS-124W M/B mode, the driver supports 16 ALSA raw MIDI substreams;
+the outs module parameter is automatically set to 16. The substream
+number gives a bitmask of which MIDI Out connectors the data should be
+sent to, with midiCnD1 sending to Out 1, midiCnD2 to Out 2, midiCnD4 to
+Out 3, and midiCnD8 to Out 4. Thus midiCnD15 sends the data to all 4 ports.
+As a special case, midiCnD0 also sends to all ports, since it is not useful
+to send the data to no ports. M/B mode has extra overhead to select the MIDI
+Out for each byte, so the aggregate data rate across all four MIDI Outs is
+at most one byte every 520 us, as compared with the full MIDI data rate of
+one byte every 320 us per port.
+
+Usage example for M/B mode:
+
+ /sbin/setserial /dev/ttyS0 uart none
+ /sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 adaptor=3
+
+The MS-124W hardware's M/A mode is currently not supported. This mode allows
+the MIDI Outs to act independently at double the aggregate throughput of M/B,
+but does not allow sending the same byte simultaneously to multiple MIDI Outs.
+The M/A protocol requires the driver to twiddle the modem control lines under
+timing constraints, so it would be a bit more complicated to implement than
+the other modes.
+
+Midiator models other than MS-124W and MS-124T are currently not supported.
+Note that the suffix letter is significant; the MS-124 and MS-124B are not
+compatible, nor are the other known models MS-101, MS-101B, MS-103, and MS-114.
+I do have documentation (tim.mann@compaq.com) that partially covers these models,
+but no units to experiment with. The MS-124W support is tested with a real unit.
+The MS-124T support is untested, but should work.
+
+The Generic driver supports multiple input and output substreams over a single
+serial port. Similar to Roland Soundcanvas mode, F5 NN is used to select the
+appropriate input or output stream (depending on the data direction).
+Additionally, the CTS signal is used to regulate the data flow. The number of
+inputs is specified by the ins parameter.
diff --git a/Documentation/sound/alsa/soc/DAI.txt b/Documentation/sound/alsa/soc/DAI.txt
new file mode 100644
index 0000000..0ebd7ea
--- /dev/null
+++ b/Documentation/sound/alsa/soc/DAI.txt
@@ -0,0 +1,56 @@
+ASoC currently supports the three main Digital Audio Interfaces (DAI) found on
+SoC controllers and portable audio CODECs today, namely AC97, I2S and PCM.
+
+
+AC97
+====
+
+ AC97 is a five wire interface commonly found on many PC sound cards. It is
+now also popular in many portable devices. This DAI has a reset line and time
+multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines.
+The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the
+frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97
+frame is 21uS long and is divided into 13 time slots.
+
+The AC97 specification can be found at :-
+http://www.intel.com/design/chipsets/audio/ac97_r23.pdf
+
+
+I2S
+===
+
+ I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and
+Rx lines are used for audio transmission, whilst the bit clock (BCLK) and
+left/right clock (LRC) synchronise the link. I2S is flexible in that either the
+controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock
+usually varies depending on the sample rate and the master system clock
+(SYSCLK). LRCLK is the same as the sample rate. A few devices support separate
+ADC and DAC LRCLKs, this allows for simultaneous capture and playback at
+different sample rates.
+
+I2S has several different operating modes:-
+
+ o I2S - MSB is transmitted on the falling edge of the first BCLK after LRC
+ transition.
+
+ o Left Justified - MSB is transmitted on transition of LRC.
+
+ o Right Justified - MSB is transmitted sample size BCLKs before LRC
+ transition.
+
+PCM
+===
+
+PCM is another 4 wire interface, very similar to I2S, which can support a more
+flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used
+to synchronise the link whilst the Tx and Rx lines are used to transmit and
+receive the audio data. Bit clock usually varies depending on sample rate
+whilst sync runs at the sample rate. PCM also supports Time Division
+Multiplexing (TDM) in that several devices can use the bus simultaneously (this
+is sometimes referred to as network mode).
+
+Common PCM operating modes:-
+
+ o Mode A - MSB is transmitted on falling edge of first BCLK after FRAME/SYNC.
+
+ o Mode B - MSB is transmitted on rising edge of FRAME/SYNC.
diff --git a/Documentation/sound/alsa/soc/clocking.txt b/Documentation/sound/alsa/soc/clocking.txt
new file mode 100644
index 0000000..b130016
--- /dev/null
+++ b/Documentation/sound/alsa/soc/clocking.txt
@@ -0,0 +1,51 @@
+Audio Clocking
+==============
+
+This text describes the audio clocking terms in ASoC and digital audio in
+general. Note: Audio clocking can be complex!
+
+
+Master Clock
+------------
+
+Every audio subsystem is driven by a master clock (sometimes referred to as MCLK
+or SYSCLK). This audio master clock can be derived from a number of sources
+(e.g. crystal, PLL, CPU clock) and is responsible for producing the correct
+audio playback and capture sample rates.
+
+Some master clocks (e.g. PLLs and CPU based clocks) are configurable in that
+their speed can be altered by software (depending on the system use and to save
+power). Other master clocks are fixed at a set frequency (i.e. crystals).
+
+
+DAI Clocks
+----------
+The Digital Audio Interface is usually driven by a Bit Clock (often referred to
+as BCLK). This clock is used to drive the digital audio data across the link
+between the codec and CPU.
+
+The DAI also has a frame clock to signal the start of each audio frame. This
+clock is sometimes referred to as LRC (left right clock) or FRAME. This clock
+runs at exactly the sample rate (LRC = Rate).
+
+Bit Clock can be generated as follows:-
+
+BCLK = MCLK / x
+
+ or
+
+BCLK = LRC * x
+
+ or
+
+BCLK = LRC * Channels * Word Size
+
+This relationship depends on the codec or SoC CPU in particular. In general
+it is best to configure BCLK to the lowest possible speed (depending on your
+rate, number of channels and word size) to save on power.
+
+It is also desirable to use the codec (if possible) to drive (or master) the
+audio clocks as it usually gives more accurate sample rates than the CPU.
+
+
+
diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt
new file mode 100644
index 0000000..1e95342
--- /dev/null
+++ b/Documentation/sound/alsa/soc/codec.txt
@@ -0,0 +1,198 @@
+ASoC Codec Driver
+=================
+
+The codec driver is generic and hardware independent code that configures the
+codec to provide audio capture and playback. It should contain no code that is
+specific to the target platform or machine. All platform and machine specific
+code should be added to the platform and machine drivers respectively.
+
+Each codec driver *must* provide the following features:-
+
+ 1) Codec DAI and PCM configuration
+ 2) Codec control IO - using I2C, 3 Wire(SPI) or both APIs
+ 3) Mixers and audio controls
+ 4) Codec audio operations
+
+Optionally, codec drivers can also provide:-
+
+ 5) DAPM description.
+ 6) DAPM event handler.
+ 7) DAC Digital mute control.
+
+Its probably best to use this guide in conjunction with the existing codec
+driver code in sound/soc/codecs/
+
+ASoC Codec driver breakdown
+===========================
+
+1 - Codec DAI and PCM configuration
+-----------------------------------
+Each codec driver must have a struct snd_soc_codec_dai to define its DAI and
+PCM capabilities and operations. This struct is exported so that it can be
+registered with the core by your machine driver.
+
+e.g.
+
+struct snd_soc_codec_dai wm8731_dai = {
+ .name = "WM8731",
+ /* playback capabilities */
+ .playback = {
+ .stream_name = "Playback",
+ .channels_min = 1,
+ .channels_max = 2,
+ .rates = WM8731_RATES,
+ .formats = WM8731_FORMATS,},
+ /* capture capabilities */
+ .capture = {
+ .stream_name = "Capture",
+ .channels_min = 1,
+ .channels_max = 2,
+ .rates = WM8731_RATES,
+ .formats = WM8731_FORMATS,},
+ /* pcm operations - see section 4 below */
+ .ops = {
+ .prepare = wm8731_pcm_prepare,
+ .hw_params = wm8731_hw_params,
+ .shutdown = wm8731_shutdown,
+ },
+ /* DAI operations - see DAI.txt */
+ .dai_ops = {
+ .digital_mute = wm8731_mute,
+ .set_sysclk = wm8731_set_dai_sysclk,
+ .set_fmt = wm8731_set_dai_fmt,
+ }
+};
+EXPORT_SYMBOL_GPL(wm8731_dai);
+
+
+2 - Codec control IO
+--------------------
+The codec can usually be controlled via an I2C or SPI style interface
+(AC97 combines control with data in the DAI). The codec drivers provide
+functions to read and write the codec registers along with supplying a
+register cache:-
+
+ /* IO control data and register cache */
+ void *control_data; /* codec control (i2c/3wire) data */
+ void *reg_cache;
+
+Codec read/write should do any data formatting and call the hardware
+read write below to perform the IO. These functions are called by the
+core and ALSA when performing DAPM or changing the mixer:-
+
+ unsigned int (*read)(struct snd_soc_codec *, unsigned int);
+ int (*write)(struct snd_soc_codec *, unsigned int, unsigned int);
+
+Codec hardware IO functions - usually points to either the I2C, SPI or AC97
+read/write:-
+
+ hw_write_t hw_write;
+ hw_read_t hw_read;
+
+
+3 - Mixers and audio controls
+-----------------------------
+All the codec mixers and audio controls can be defined using the convenience
+macros defined in soc.h.
+
+ #define SOC_SINGLE(xname, reg, shift, mask, invert)
+
+Defines a single control as follows:-
+
+ xname = Control name e.g. "Playback Volume"
+ reg = codec register
+ shift = control bit(s) offset in register
+ mask = control bit size(s) e.g. mask of 7 = 3 bits
+ invert = the control is inverted
+
+Other macros include:-
+
+ #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)
+
+A stereo control
+
+ #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)
+
+A stereo control spanning 2 registers
+
+ #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)
+
+Defines an single enumerated control as follows:-
+
+ xreg = register
+ xshift = control bit(s) offset in register
+ xmask = control bit(s) size
+ xtexts = pointer to array of strings that describe each setting
+
+ #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)
+
+Defines a stereo enumerated control
+
+
+4 - Codec Audio Operations
+--------------------------
+The codec driver also supports the following ALSA operations:-
+
+/* SoC audio ops */
+struct snd_soc_ops {
+ int (*startup)(struct snd_pcm_substream *);
+ void (*shutdown)(struct snd_pcm_substream *);
+ int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
+ int (*hw_free)(struct snd_pcm_substream *);
+ int (*prepare)(struct snd_pcm_substream *);
+};
+
+Please refer to the ALSA driver PCM documentation for details.
+http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
+
+
+5 - DAPM description.
+---------------------
+The Dynamic Audio Power Management description describes the codec power
+components and their relationships and registers to the ASoC core.
+Please read dapm.txt for details of building the description.
+
+Please also see the examples in other codec drivers.
+
+
+6 - DAPM event handler
+----------------------
+This function is a callback that handles codec domain PM calls and system
+domain PM calls (e.g. suspend and resume). It is used to put the codec
+to sleep when not in use.
+
+Power states:-
+
+ SNDRV_CTL_POWER_D0: /* full On */
+ /* vref/mid, clk and osc on, active */
+
+ SNDRV_CTL_POWER_D1: /* partial On */
+ SNDRV_CTL_POWER_D2: /* partial On */
+
+ SNDRV_CTL_POWER_D3hot: /* Off, with power */
+ /* everything off except vref/vmid, inactive */
+
+ SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
+
+
+7 - Codec DAC digital mute control
+----------------------------------
+Most codecs have a digital mute before the DACs that can be used to
+minimise any system noise. The mute stops any digital data from
+entering the DAC.
+
+A callback can be created that is called by the core for each codec DAI
+when the mute is applied or freed.
+
+i.e.
+
+static int wm8974_mute(struct snd_soc_codec *codec,
+ struct snd_soc_codec_dai *dai, int mute)
+{
+ u16 mute_reg = wm8974_read_reg_cache(codec, WM8974_DAC) & 0xffbf;
+ if(mute)
+ wm8974_write(codec, WM8974_DAC, mute_reg | 0x40);
+ else
+ wm8974_write(codec, WM8974_DAC, mute_reg);
+ return 0;
+}
diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/alsa/soc/dapm.txt
new file mode 100644
index 0000000..46f9684
--- /dev/null
+++ b/Documentation/sound/alsa/soc/dapm.txt
@@ -0,0 +1,290 @@
+Dynamic Audio Power Management for Portable Devices
+===================================================
+
+1. Description
+==============
+
+Dynamic Audio Power Management (DAPM) is designed to allow portable
+Linux devices to use the minimum amount of power within the audio
+subsystem at all times. It is independent of other kernel PM and as
+such, can easily co-exist with the other PM systems.
+
+DAPM is also completely transparent to all user space applications as
+all power switching is done within the ASoC core. No code changes or
+recompiling are required for user space applications. DAPM makes power
+switching decisions based upon any audio stream (capture/playback)
+activity and audio mixer settings within the device.
+
+DAPM spans the whole machine. It covers power control within the entire
+audio subsystem, this includes internal codec power blocks and machine
+level power systems.
+
+There are 4 power domains within DAPM
+
+ 1. Codec domain - VREF, VMID (core codec and audio power)
+ Usually controlled at codec probe/remove and suspend/resume, although
+ can be set at stream time if power is not needed for sidetone, etc.
+
+ 2. Platform/Machine domain - physically connected inputs and outputs
+ Is platform/machine and user action specific, is configured by the
+ machine driver and responds to asynchronous events e.g when HP
+ are inserted
+
+ 3. Path domain - audio susbsystem signal paths
+ Automatically set when mixer and mux settings are changed by the user.
+ e.g. alsamixer, amixer.
+
+ 4. Stream domain - DACs and ADCs.
+ Enabled and disabled when stream playback/capture is started and
+ stopped respectively. e.g. aplay, arecord.
+
+All DAPM power switching decisions are made automatically by consulting an audio
+routing map of the whole machine. This map is specific to each machine and
+consists of the interconnections between every audio component (including
+internal codec components). All audio components that effect power are called
+widgets hereafter.
+
+
+2. DAPM Widgets
+===============
+
+Audio DAPM widgets fall into a number of types:-
+
+ o Mixer - Mixes several analog signals into a single analog signal.
+ o Mux - An analog switch that outputs only one of many inputs.
+ o PGA - A programmable gain amplifier or attenuation widget.
+ o ADC - Analog to Digital Converter
+ o DAC - Digital to Analog Converter
+ o Switch - An analog switch
+ o Input - A codec input pin
+ o Output - A codec output pin
+ o Headphone - Headphone (and optional Jack)
+ o Mic - Mic (and optional Jack)
+ o Line - Line Input/Output (and optional Jack)
+ o Speaker - Speaker
+ o Pre - Special PRE widget (exec before all others)
+ o Post - Special POST widget (exec after all others)
+
+(Widgets are defined in include/sound/soc-dapm.h)
+
+Widgets are usually added in the codec driver and the machine driver. There are
+convenience macros defined in soc-dapm.h that can be used to quickly build a
+list of widgets of the codecs and machines DAPM widgets.
+
+Most widgets have a name, register, shift and invert. Some widgets have extra
+parameters for stream name and kcontrols.
+
+
+2.1 Stream Domain Widgets
+-------------------------
+
+Stream Widgets relate to the stream power domain and only consist of ADCs
+(analog to digital converters) and DACs (digital to analog converters).
+
+Stream widgets have the following format:-
+
+SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert),
+
+NOTE: the stream name must match the corresponding stream name in your codec
+snd_soc_codec_dai.
+
+e.g. stream widgets for HiFi playback and capture
+
+SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1),
+SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1),
+
+
+2.2 Path Domain Widgets
+-----------------------
+
+Path domain widgets have a ability to control or affect the audio signal or
+audio paths within the audio subsystem. They have the following form:-
+
+SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls)
+
+Any widget kcontrols can be set using the controls and num_controls members.
+
+e.g. Mixer widget (the kcontrols are declared first)
+
+/* Output Mixer */
+static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = {
+SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0),
+SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0),
+SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0),
+};
+
+SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls,
+ ARRAY_SIZE(wm8731_output_mixer_controls)),
+
+
+2.3 Platform/Machine domain Widgets
+-----------------------------------
+
+Machine widgets are different from codec widgets in that they don't have a
+codec register bit associated with them. A machine widget is assigned to each
+machine audio component (non codec) that can be independently powered. e.g.
+
+ o Speaker Amp
+ o Microphone Bias
+ o Jack connectors
+
+A machine widget can have an optional call back.
+
+e.g. Jack connector widget for an external Mic that enables Mic Bias
+when the Mic is inserted:-
+
+static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
+{
+ gpio_set_value(SPITZ_GPIO_MIC_BIAS, SND_SOC_DAPM_EVENT_ON(event));
+ return 0;
+}
+
+SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias),
+
+
+2.4 Codec Domain
+----------------
+
+The codec power domain has no widgets and is handled by the codecs DAPM event
+handler. This handler is called when the codec powerstate is changed wrt to any
+stream event or by kernel PM events.
+
+
+2.5 Virtual Widgets
+-------------------
+
+Sometimes widgets exist in the codec or machine audio map that don't have any
+corresponding soft power control. In this case it is necessary to create
+a virtual widget - a widget with no control bits e.g.
+
+SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0),
+
+This can be used to merge to signal paths together in software.
+
+After all the widgets have been defined, they can then be added to the DAPM
+subsystem individually with a call to snd_soc_dapm_new_control().
+
+
+3. Codec Widget Interconnections
+================================
+
+Widgets are connected to each other within the codec and machine by audio paths
+(called interconnections). Each interconnection must be defined in order to
+create a map of all audio paths between widgets.
+
+This is easiest with a diagram of the codec (and schematic of the machine audio
+system), as it requires joining widgets together via their audio signal paths.
+
+e.g., from the WM8731 output mixer (wm8731.c)
+
+The WM8731 output mixer has 3 inputs (sources)
+
+ 1. Line Bypass Input
+ 2. DAC (HiFi playback)
+ 3. Mic Sidetone Input
+
+Each input in this example has a kcontrol associated with it (defined in example
+above) and is connected to the output mixer via it's kcontrol name. We can now
+connect the destination widget (wrt audio signal) with it's source widgets.
+
+ /* output mixer */
+ {"Output Mixer", "Line Bypass Switch", "Line Input"},
+ {"Output Mixer", "HiFi Playback Switch", "DAC"},
+ {"Output Mixer", "Mic Sidetone Switch", "Mic Bias"},
+
+So we have :-
+
+ Destination Widget <=== Path Name <=== Source Widget
+
+Or:-
+
+ Sink, Path, Source
+
+Or :-
+
+ "Output Mixer" is connected to the "DAC" via the "HiFi Playback Switch".
+
+When there is no path name connecting widgets (e.g. a direct connection) we
+pass NULL for the path name.
+
+Interconnections are created with a call to:-
+
+snd_soc_dapm_connect_input(codec, sink, path, source);
+
+Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
+interconnections have been registered with the core. This causes the core to
+scan the codec and machine so that the internal DAPM state matches the
+physical state of the machine.
+
+
+3.1 Machine Widget Interconnections
+-----------------------------------
+Machine widget interconnections are created in the same way as codec ones and
+directly connect the codec pins to machine level widgets.
+
+e.g. connects the speaker out codec pins to the internal speaker.
+
+ /* ext speaker connected to codec pins LOUT2, ROUT2 */
+ {"Ext Spk", NULL , "ROUT2"},
+ {"Ext Spk", NULL , "LOUT2"},
+
+This allows the DAPM to power on and off pins that are connected (and in use)
+and pins that are NC respectively.
+
+
+4 Endpoint Widgets
+===================
+An endpoint is a start or end point (widget) of an audio signal within the
+machine and includes the codec. e.g.
+
+ o Headphone Jack
+ o Internal Speaker
+ o Internal Mic
+ o Mic Jack
+ o Codec Pins
+
+When a codec pin is NC it can be marked as not used with a call to
+
+snd_soc_dapm_set_endpoint(codec, "Widget Name", 0);
+
+The last argument is 0 for inactive and 1 for active. This way the pin and its
+input widget will never be powered up and consume power.
+
+This also applies to machine widgets. e.g. if a headphone is connected to a
+jack then the jack can be marked active. If the headphone is removed, then
+the headphone jack can be marked inactive.
+
+
+5 DAPM Widget Events
+====================
+
+Some widgets can register their interest with the DAPM core in PM events.
+e.g. A Speaker with an amplifier registers a widget so the amplifier can be
+powered only when the spk is in use.
+
+/* turn speaker amplifier on/off depending on use */
+static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event)
+{
+ gpio_set_value(CORGI_GPIO_APM_ON, SND_SOC_DAPM_EVENT_ON(event));
+ return 0;
+}
+
+/* corgi machine dapm widgets */
+static const struct snd_soc_dapm_widget wm8731_dapm_widgets =
+ SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event);
+
+Please see soc-dapm.h for all other widgets that support events.
+
+
+5.1 Event types
+---------------
+
+The following event types are supported by event widgets.
+
+/* dapm event types */
+#define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */
+#define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */
+#define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */
+#define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */
+#define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */
+#define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */
diff --git a/Documentation/sound/alsa/soc/machine.txt b/Documentation/sound/alsa/soc/machine.txt
new file mode 100644
index 0000000..f370e7d
--- /dev/null
+++ b/Documentation/sound/alsa/soc/machine.txt
@@ -0,0 +1,113 @@
+ASoC Machine Driver
+===================
+
+The ASoC machine (or board) driver is the code that glues together the platform
+and codec drivers.
+
+The machine driver can contain codec and platform specific code. It registers
+the audio subsystem with the kernel as a platform device and is represented by
+the following struct:-
+
+/* SoC machine */
+struct snd_soc_machine {
+ char *name;
+
+ int (*probe)(struct platform_device *pdev);
+ int (*remove)(struct platform_device *pdev);
+
+ /* the pre and post PM functions are used to do any PM work before and
+ * after the codec and DAIs do any PM work. */
+ int (*suspend_pre)(struct platform_device *pdev, pm_message_t state);
+ int (*suspend_post)(struct platform_device *pdev, pm_message_t state);
+ int (*resume_pre)(struct platform_device *pdev);
+ int (*resume_post)(struct platform_device *pdev);
+
+ /* machine stream operations */
+ struct snd_soc_ops *ops;
+
+ /* CPU <--> Codec DAI links */
+ struct snd_soc_dai_link *dai_link;
+ int num_links;
+};
+
+probe()/remove()
+----------------
+probe/remove are optional. Do any machine specific probe here.
+
+
+suspend()/resume()
+------------------
+The machine driver has pre and post versions of suspend and resume to take care
+of any machine audio tasks that have to be done before or after the codec, DAIs
+and DMA is suspended and resumed. Optional.
+
+
+Machine operations
+------------------
+The machine specific audio operations can be set here. Again this is optional.
+
+
+Machine DAI Configuration
+-------------------------
+The machine DAI configuration glues all the codec and CPU DAIs together. It can
+also be used to set up the DAI system clock and for any machine related DAI
+initialisation e.g. the machine audio map can be connected to the codec audio
+map, unconnected codec pins can be set as such. Please see corgi.c, spitz.c
+for examples.
+
+struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.
+
+/* corgi digital audio interface glue - connects codec <--> CPU */
+static struct snd_soc_dai_link corgi_dai = {
+ .name = "WM8731",
+ .stream_name = "WM8731",
+ .cpu_dai = &pxa_i2s_dai,
+ .codec_dai = &wm8731_dai,
+ .init = corgi_wm8731_init,
+ .ops = &corgi_ops,
+};
+
+struct snd_soc_machine then sets up the machine with it's DAIs. e.g.
+
+/* corgi audio machine driver */
+static struct snd_soc_machine snd_soc_machine_corgi = {
+ .name = "Corgi",
+ .dai_link = &corgi_dai,
+ .num_links = 1,
+};
+
+
+Machine Audio Subsystem
+-----------------------
+
+The machine soc device glues the platform, machine and codec driver together.
+Private data can also be set here. e.g.
+
+/* corgi audio private data */
+static struct wm8731_setup_data corgi_wm8731_setup = {
+ .i2c_address = 0x1b,
+};
+
+/* corgi audio subsystem */
+static struct snd_soc_device corgi_snd_devdata = {
+ .machine = &snd_soc_machine_corgi,
+ .platform = &pxa2xx_soc_platform,
+ .codec_dev = &soc_codec_dev_wm8731,
+ .codec_data = &corgi_wm8731_setup,
+};
+
+
+Machine Power Map
+-----------------
+
+The machine driver can optionally extend the codec power map and to become an
+audio power map of the audio subsystem. This allows for automatic power up/down
+of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack
+sockets in the machine init function. See soc/pxa/spitz.c and dapm.txt for
+details.
+
+
+Machine Controls
+----------------
+
+Machine specific audio mixer controls can be added in the DAI init function.
diff --git a/Documentation/sound/alsa/soc/overview.txt b/Documentation/sound/alsa/soc/overview.txt
new file mode 100644
index 0000000..1e4c6d3
--- /dev/null
+++ b/Documentation/sound/alsa/soc/overview.txt
@@ -0,0 +1,86 @@
+ALSA SoC Layer
+==============
+
+The overall project goal of the ALSA System on Chip (ASoC) layer is to
+provide better ALSA support for embedded system-on-chip processors (e.g.
+pxa2xx, au1x00, iMX, etc) and portable audio codecs. Prior to the ASoC
+subsystem there was some support in the kernel for SoC audio, however it
+had some limitations:-
+
+ * Codec drivers were often tightly coupled to the underlying SoC
+ CPU. This is not ideal and leads to code duplication - for example,
+ Linux had different wm8731 drivers for 4 different SoC platforms.
+
+ * There was no standard method to signal user initiated audio events (e.g.
+ Headphone/Mic insertion, Headphone/Mic detection after an insertion
+ event). These are quite common events on portable devices and often require
+ machine specific code to re-route audio, enable amps, etc., after such an
+ event.
+
+ * Drivers tended to power up the entire codec when playing (or
+ recording) audio. This is fine for a PC, but tends to waste a lot of
+ power on portable devices. There was also no support for saving
+ power via changing codec oversampling rates, bias currents, etc.
+
+
+ASoC Design
+===========
+
+The ASoC layer is designed to address these issues and provide the following
+features :-
+
+ * Codec independence. Allows reuse of codec drivers on other platforms
+ and machines.
+
+ * Easy I2S/PCM audio interface setup between codec and SoC. Each SoC
+ interface and codec registers it's audio interface capabilities with the
+ core and are subsequently matched and configured when the application
+ hardware parameters are known.
+
+ * Dynamic Audio Power Management (DAPM). DAPM automatically sets the codec to
+ its minimum power state at all times. This includes powering up/down
+ internal power blocks depending on the internal codec audio routing and any
+ active streams.
+
+ * Pop and click reduction. Pops and clicks can be reduced by powering the
+ codec up/down in the correct sequence (including using digital mute). ASoC
+ signals the codec when to change power states.
+
+ * Machine specific controls: Allow machines to add controls to the sound card
+ (e.g. volume control for speaker amplifier).
+
+To achieve all this, ASoC basically splits an embedded audio system into 3
+components :-
+
+ * Codec driver: The codec driver is platform independent and contains audio
+ controls, audio interface capabilities, codec DAPM definition and codec IO
+ functions.
+
+ * Platform driver: The platform driver contains the audio DMA engine and audio
+ interface drivers (e.g. I2S, AC97, PCM) for that platform.
+
+ * Machine driver: The machine driver handles any machine specific controls and
+ audio events (e.g. turning on an amp at start of playback).
+
+
+Documentation
+=============
+
+The documentation is spilt into the following sections:-
+
+overview.txt: This file.
+
+codec.txt: Codec driver internals.
+
+DAI.txt: Description of Digital Audio Interface standards and how to configure
+a DAI within your codec and CPU DAI drivers.
+
+dapm.txt: Dynamic Audio Power Management
+
+platform.txt: Platform audio DMA and DAI.
+
+machine.txt: Machine driver internals.
+
+pop_clicks.txt: How to minimise audio artifacts.
+
+clocking.txt: ASoC clocking for best power performance.
diff --git a/Documentation/sound/alsa/soc/platform.txt b/Documentation/sound/alsa/soc/platform.txt
new file mode 100644
index 0000000..b681d17
--- /dev/null
+++ b/Documentation/sound/alsa/soc/platform.txt
@@ -0,0 +1,58 @@
+ASoC Platform Driver
+====================
+
+An ASoC platform driver can be divided into audio DMA and SoC DAI configuration
+and control. The platform drivers only target the SoC CPU and must have no board
+specific code.
+
+Audio DMA
+=========
+
+The platform DMA driver optionally supports the following ALSA operations:-
+
+/* SoC audio ops */
+struct snd_soc_ops {
+ int (*startup)(struct snd_pcm_substream *);
+ void (*shutdown)(struct snd_pcm_substream *);
+ int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
+ int (*hw_free)(struct snd_pcm_substream *);
+ int (*prepare)(struct snd_pcm_substream *);
+ int (*trigger)(struct snd_pcm_substream *, int);
+};
+
+The platform driver exports its DMA functionality via struct snd_soc_platform:-
+
+struct snd_soc_platform {
+ char *name;
+
+ int (*probe)(struct platform_device *pdev);
+ int (*remove)(struct platform_device *pdev);
+ int (*suspend)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
+ int (*resume)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
+
+ /* pcm creation and destruction */
+ int (*pcm_new)(struct snd_card *, struct snd_soc_codec_dai *, struct snd_pcm *);
+ void (*pcm_free)(struct snd_pcm *);
+
+ /* platform stream ops */
+ struct snd_pcm_ops *pcm_ops;
+};
+
+Please refer to the ALSA driver documentation for details of audio DMA.
+http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
+
+An example DMA driver is soc/pxa/pxa2xx-pcm.c
+
+
+SoC DAI Drivers
+===============
+
+Each SoC DAI driver must provide the following features:-
+
+ 1) Digital audio interface (DAI) description
+ 2) Digital audio interface configuration
+ 3) PCM's description
+ 4) SYSCLK configuration
+ 5) Suspend and resume (optional)
+
+Please see codec.txt for a description of items 1 - 4.
diff --git a/Documentation/sound/alsa/soc/pops_clicks.txt b/Documentation/sound/alsa/soc/pops_clicks.txt
new file mode 100644
index 0000000..e1e74da
--- /dev/null
+++ b/Documentation/sound/alsa/soc/pops_clicks.txt
@@ -0,0 +1,52 @@
+Audio Pops and Clicks
+=====================
+
+Pops and clicks are unwanted audio artifacts caused by the powering up and down
+of components within the audio subsystem. This is noticeable on PCs when an
+audio module is either loaded or unloaded (at module load time the sound card is
+powered up and causes a popping noise on the speakers).
+
+Pops and clicks can be more frequent on portable systems with DAPM. This is
+because the components within the subsystem are being dynamically powered
+depending on the audio usage and this can subsequently cause a small pop or
+click every time a component power state is changed.
+
+
+Minimising Playback Pops and Clicks
+===================================
+
+Playback pops in portable audio subsystems cannot be completely eliminated
+currently, however future audio codec hardware will have better pop and click
+suppression. Pops can be reduced within playback by powering the audio
+components in a specific order. This order is different for startup and
+shutdown and follows some basic rules:-
+
+ Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute
+
+ Shutdown Order :- Digital Mute --> Output PGA --> Mixers --> DAC
+
+This assumes that the codec PCM output path from the DAC is via a mixer and then
+a PGA (programmable gain amplifier) before being output to the speakers.
+
+
+Minimising Capture Pops and Clicks
+==================================
+
+Capture artifacts are somewhat easier to get rid as we can delay activating the
+ADC until all the pops have occurred. This follows similar power rules to
+playback in that components are powered in a sequence depending upon stream
+startup or shutdown.
+
+ Startup Order - Input PGA --> Mixers --> ADC
+
+ Shutdown Order - ADC --> Mixers --> Input PGA
+
+
+Zipper Noise
+============
+An unwanted zipper noise can occur within the audio playback or capture stream
+when a volume control is changed near its maximum gain value. The zipper noise
+is heard when the gain increase or decrease changes the mean audio signal
+amplitude too quickly. It can be minimised by enabling the zero cross setting
+for each volume control. The ZC forces the gain change to occur when the signal
+crosses the zero amplitude line.
diff --git a/Documentation/sound/oss/ALS b/Documentation/sound/oss/ALS
new file mode 100644
index 0000000..d01ffbf
--- /dev/null
+++ b/Documentation/sound/oss/ALS
@@ -0,0 +1,66 @@
+ALS-007/ALS-100/ALS-200 based sound cards
+=========================================
+
+Support for sound cards based around the Avance Logic
+ALS-007/ALS-100/ALS-200 chip is included. These chips are a single
+chip PnP sound solution which is mostly hardware compatible with the
+Sound Blaster 16 card, with most differences occurring in the use of
+the mixer registers. For this reason the ALS code is integrated
+as part of the Sound Blaster 16 driver (adding only 800 bytes to the
+SB16 driver).
+
+To use an ALS sound card under Linux, enable the following options as
+modules in the sound configuration section of the kernel config:
+ - 100% Sound Blaster compatibles (SB16/32/64, ESS, Jazz16) support
+ - FM synthesizer (YM3812/OPL-3) support
+ - standalone MPU401 support may be required for some cards; for the
+ ALS-007, when using isapnptools, it is required
+Since the ALS-007/100/200 are PnP cards, ISAPnP support should probably be
+compiled in. If kernel level PnP support is not included, isapnptools will
+be required to configure the card before the sound modules are loaded.
+
+When using kernel level ISAPnP, the kernel should correctly identify and
+configure all resources required by the card when the "sb" module is
+inserted. Note that the ALS-007 does not have a 16 bit DMA channel and that
+the MPU401 interface on this card uses a different interrupt to the audio
+section. This should all be correctly configured by the kernel; if problems
+with the MPU401 interface surface, try using the standalone MPU401 module,
+passing "0" as the "sb" module's "mpu_io" module parameter to prevent the
+soundblaster driver attempting to register the MPU401 itself. The onboard
+synth device can be accessed using the "opl3" module.
+
+If isapnptools is used to wake up the sound card (as in 2.2.x), the settings
+of the card's resources should be passed to the kernel modules ("sb", "opl3"
+and "mpu401") using the module parameters. When configuring an ALS-007, be
+sure to specify different IRQs for the audio and MPU401 sections - this card
+requires they be different. For "sb", "io", "irq" and "dma" should be set
+to the same values used to configure the audio section of the card with
+isapnp. "dma16" should be explicitly set to "-1" for an ALS-007 since this
+card does not have a 16 bit dma channel; if not specified the kernel will
+default to using channel 5 anyway which will cause audio not to work.
+"mpu_io" should be set to 0. The "io" parameter of the "opl3" module should
+also agree with the setting used by isapnp. To get the MPU401 interface
+working on an ALS-007 card, the "mpu401" module will be required since this
+card uses separate IRQs for the audio and MPU401 sections and there is no
+parameter available to pass a different IRQ to the "sb" driver (whose
+inbuilt MPU401 driver would otherwise be fine). Insert the mpu401 module
+passing appropriate values using the "io" and "irq" parameters.
+
+The resulting sound driver will provide the following capabilities:
+ - 8 and 16 bit audio playback
+ - 8 and 16 bit audio recording
+ - Software selection of record source (line in, CD, FM, mic, master)
+ - Record and playback of midi data via the external MPU-401
+ - Playback of midi data using inbuilt FM synthesizer
+ - Control of the ALS-007 mixer via any OSS-compatible mixer programs.
+ Controls available are Master (L&R), Line in (L&R), CD (L&R),
+ DSP/PCM/audio out (L&R), FM (L&R) and Mic in (mono).
+
+Jonathan Woithe
+jwoithe@physics.adelaide.edu.au
+30 March 1998
+
+Modified 2000-02-26 by Dave Forrest, drf5n@virginia.edu to add ALS100/ALS200
+Modified 2000-04-10 by Paul Laufer, pelaufer@csupomona.edu to add ISAPnP info.
+Modified 2000-11-19 by Jonathan Woithe, jwoithe@physics.adelaide.edu.au
+ - updated information for kernel 2.4.x.
diff --git a/Documentation/sound/oss/AudioExcelDSP16 b/Documentation/sound/oss/AudioExcelDSP16
new file mode 100644
index 0000000..c0f0892
--- /dev/null
+++ b/Documentation/sound/oss/AudioExcelDSP16
@@ -0,0 +1,101 @@
+Driver
+------
+
+Informations about Audio Excel DSP 16 driver can be found in the source
+file aedsp16.c
+Please, read the head of the source before using it. It contain useful
+informations.
+
+Configuration
+-------------
+
+The Audio Excel configuration, is now done with the standard Linux setup.
+You have to configure the sound card (Sound Blaster or Microsoft Sound System)
+and, if you want it, the Roland MPU-401 (do not use the Sound Blaster MPU-401,
+SB-MPU401) in the main driver menu. Activate the lowlevel drivers then select
+the Audio Excel hardware that you want to initialize. Check the IRQ/DMA/MIRQ
+of the Audio Excel initialization: it must be the same as the SBPRO (or MSS)
+setup. If the parameters are different, correct it.
+I you own a Gallant's audio card based on SC-6600, activate the SC-6600 support.
+If you want to change the configuration of the sound board, be sure to
+check off all the configuration items before re-configure it.
+
+Module parameters
+-----------------
+To use this driver as a module, you must configure some module parameters, to
+set up I/O addresses, IRQ lines and DMA channels. Some parameters are
+mandatory while some others are optional. Here a list of parameters you can
+use with this module:
+
+Name Description
+==== ===========
+MANDATORY
+io I/O base address (0x220 or 0x240)
+irq irq line (5, 7, 9, 10 or 11)
+dma dma channel (0, 1 or 3)
+
+OPTIONAL
+mss_base I/O base address for activate MSS mode (default SBPRO)
+ (0x530 or 0xE80)
+mpu_base I/O base address for activate MPU-401 mode
+ (0x300, 0x310, 0x320 or 0x330)
+mpu_irq MPU-401 irq line (5, 7, 9, 10 or 0)
+
+The /etc/modprobe.conf will have lines like this:
+
+options opl3 io=0x388
+options ad1848 io=0x530 irq=11 dma=3
+options aedsp16 io=0x220 irq=11 dma=3 mss_base=0x530
+
+Where the aedsp16 options are the options for this driver while opl3 and
+ad1848 are the corresponding options for the MSS and OPL3 modules.
+
+Loading MSS and OPL3 needs to pre load the aedsp16 module to set up correctly
+the sound card. Installation dependencies must be written in the modprobe.conf
+file:
+
+install ad1848 /sbin/modprobe aedsp16 && /sbin/modprobe -i ad1848
+install opl3 /sbin/modprobe aedsp16 && /sbin/modprobe -i opl3
+
+Then you must load the sound modules stack in this order:
+sound -> aedsp16 -> [ ad1848, opl3 ]
+
+With the above configuration, loading ad1848 or opl3 modules, will
+automatically load all the sound stack.
+
+Sound cards supported
+---------------------
+This driver supports the SC-6000 and SC-6600 based Gallant's sound card.
+It don't support the Audio Excel DSP 16 III (try the SC-6600 code).
+I'm working on the III version of the card: if someone have useful
+informations about it, please let me know.
+For all the non-supported audio cards, you have to boot MS-DOS (or WIN95)
+activating the audio card with the MS-DOS device driver, then you have to
+<ctrl>-<alt>-<del> and boot Linux.
+Follow these steps:
+
+1) Compile Linux kernel with standard sound driver, using the emulation
+ you want, with the parameters of your audio card,
+ e.g. Microsoft Sound System irq10 dma3
+2) Install your new kernel as the default boot kernel.
+3) Boot MS-DOS and configure the audio card with the boot time device
+ driver, for MSS irq10 dma3 in our example.
+4) <ctrl>-<alt>-<del> and boot Linux. This will maintain the DOS configuration
+ and will boot the new kernel with sound driver. The sound driver will find
+ the audio card and will recognize and attach it.
+
+Reports on User successes
+-------------------------
+
+> Date: Mon, 29 Jul 1996 08:35:40 +0100
+> From: Mr S J Greenaway <sjg95@unixfe.rl.ac.uk>
+> To: riccardo@cdc8g5.cdc.polimi.it (Riccardo Facchetti)
+> Subject: Re: Audio Excel DSP 16 initialization code
+>
+> Just to let you know got my Audio Excel (emulating a MSS) working
+> with my original SB16, thanks for the driver!
+
+
+Last revised: 20 August 1998
+Riccardo Facchetti
+fizban@tin.it
diff --git a/Documentation/sound/oss/CMI8330 b/Documentation/sound/oss/CMI8330
new file mode 100644
index 0000000..9c439f1
--- /dev/null
+++ b/Documentation/sound/oss/CMI8330
@@ -0,0 +1,153 @@
+Documentation for CMI 8330 (SoundPRO)
+-------------------------------------
+Alessandro Zummo <azummo@ita.flashnet.it>
+
+( Be sure to read Documentation/sound/oss/SoundPro too )
+
+
+This adapter is now directly supported by the sb driver.
+
+ The only thing you have to do is to compile the kernel sound
+support as a module and to enable kernel ISAPnP support,
+as shown below.
+
+
+CONFIG_SOUND=m
+CONFIG_SOUND_SB=m
+
+CONFIG_PNP=y
+CONFIG_ISAPNP=y
+
+
+and optionally:
+
+
+CONFIG_SOUND_MPU401=m
+
+ for MPU401 support.
+
+
+(I suggest you to use "make menuconfig" or "make xconfig"
+ for a more comfortable configuration editing)
+
+
+
+Then you can do
+
+ modprobe sb
+
+and everything will be (hopefully) configured.
+
+You should get something similar in syslog:
+
+sb: CMI8330 detected.
+sb: CMI8330 sb base located at 0x220
+sb: CMI8330 mpu base located at 0x330
+sb: CMI8330 mail reports to Alessandro Zummo <azummo@ita.flashnet.it>
+sb: ISAPnP reports CMI 8330 SoundPRO at i/o 0x220, irq 7, dma 1,5
+
+
+
+
+The old documentation file follows for reference
+purposes.
+
+
+How to enable CMI 8330 (SOUNDPRO) soundchip on Linux
+------------------------------------------
+Stefan Laudat <Stefan.Laudat@asit.ro>
+
+[Note: The CMI 8338 is unrelated and is supported by cmpci.o]
+
+
+ In order to use CMI8330 under Linux you just have to use a proper isapnp.conf, a good isapnp and a little bit of patience. I use isapnp 1.17, but
+you may get a better one I guess at http://www.roestock.demon.co.uk/isapnptools/.
+
+ Of course you will have to compile kernel sound support as module, as shown below:
+
+CONFIG_SOUND=m
+CONFIG_SOUND_OSS=m
+CONFIG_SOUND_SB=m
+CONFIG_SOUND_ADLIB=m
+CONFIG_SOUND_MPU401=m
+# Mikro$chaft sound system (kinda useful here ;))
+CONFIG_SOUND_MSS=m
+
+ The /etc/isapnp.conf file will be:
+
+<snip below>
+
+
+(READPORT 0x0203)
+(ISOLATE PRESERVE)
+(IDENTIFY *)
+(VERBOSITY 2)
+(CONFLICT (IO FATAL)(IRQ FATAL)(DMA FATAL)(MEM FATAL)) # or WARNING
+(VERIFYLD N)
+
+
+# WSS
+
+(CONFIGURE CMI0001/16777472 (LD 0
+(IO 0 (SIZE 8) (BASE 0x0530))
+(IO 1 (SIZE 8) (BASE 0x0388))
+(INT 0 (IRQ 7 (MODE +E)))
+(DMA 0 (CHANNEL 0))
+(NAME "CMI0001/16777472[0]{CMI8330/C3D Audio Adapter}")
+(ACT Y)
+))
+
+# MPU
+
+(CONFIGURE CMI0001/16777472 (LD 1
+(IO 0 (SIZE 2) (BASE 0x0330))
+(INT 0 (IRQ 11 (MODE +E)))
+(NAME "CMI0001/16777472[1]{CMI8330/C3D Audio Adapter}")
+(ACT Y)
+))
+
+# Joystick
+
+(CONFIGURE CMI0001/16777472 (LD 2
+(IO 0 (SIZE 8) (BASE 0x0200))
+(NAME "CMI0001/16777472[2]{CMI8330/C3D Audio Adapter}")
+(ACT Y)
+))
+
+# SoundBlaster
+
+(CONFIGURE CMI0001/16777472 (LD 3
+(IO 0 (SIZE 16) (BASE 0x0220))
+(INT 0 (IRQ 5 (MODE +E)))
+(DMA 0 (CHANNEL 1))
+(DMA 1 (CHANNEL 5))
+(NAME "CMI0001/16777472[3]{CMI8330/C3D Audio Adapter}")
+(ACT Y)
+))
+
+
+(WAITFORKEY)
+
+<end of snip>
+
+ The module sequence is trivial:
+
+/sbin/insmod soundcore
+/sbin/insmod sound
+/sbin/insmod uart401
+# insert this first
+/sbin/insmod ad1848 io=0x530 irq=7 dma=0 soundpro=1
+# The sb module is an alternative to the ad1848 (Microsoft Sound System)
+# Anyhow, this is full duplex and has MIDI
+/sbin/insmod sb io=0x220 dma=1 dma16=5 irq=5 mpu_io=0x330
+
+
+
+Alma Chao <elysian@ethereal.torsion.org> suggests the following /etc/modprobe.conf:
+
+alias sound ad1848
+alias synth0 opl3
+options ad1848 io=0x530 irq=7 dma=0 soundpro=1
+options opl3 io=0x388
+
+
diff --git a/Documentation/sound/oss/CS4232 b/Documentation/sound/oss/CS4232
new file mode 100644
index 0000000..7d6af7a
--- /dev/null
+++ b/Documentation/sound/oss/CS4232
@@ -0,0 +1,23 @@
+To configure the Crystal CS423x sound chip and activate its DSP functions,
+modules may be loaded in this order:
+
+ modprobe sound
+ insmod ad1848
+ insmod uart401
+ insmod cs4232 io=* irq=* dma=* dma2=*
+
+This is the meaning of the parameters:
+
+ io--I/O address of the Windows Sound System (normally 0x534)
+ irq--IRQ of this device
+ dma and dma2--DMA channels (DMA2 may be 0)
+
+On some cards, the board attempts to do non-PnP setup, and fails. If you
+have problems, use Linux' PnP facilities.
+
+To get MIDI facilities add
+
+ insmod opl3 io=*
+
+where "io" is the I/O address of the OPL3 synthesizer. This will be shown
+in /proc/sys/pnp and is normally 0x388.
diff --git a/Documentation/sound/oss/ESS b/Documentation/sound/oss/ESS
new file mode 100644
index 0000000..bba93b4
--- /dev/null
+++ b/Documentation/sound/oss/ESS
@@ -0,0 +1,34 @@
+Documentation for the ESS AudioDrive chips
+
+In 2.4 kernels the SoundBlaster driver not only tries to detect an ESS chip, it
+tries to detect the type of ESS chip too. The correct detection of the chip
+doesn't always succeed however, so unless you use the kernel isapnp facilities
+(and you chip is pnp capable) the default behaviour is 2.0 behaviour which
+means: only detect ES688 and ES1688.
+
+All ESS chips now have a recording level setting. This is a need-to-have for
+people who want to use their ESS for recording sound.
+
+Every chip that's detected as a later-than-es1688 chip has a 6 bits logarithmic
+master volume control.
+
+Every chip that's detected as a ES1887 now has Full Duplex support. Made a
+little testprogram that shows that is works, haven't seen a real program that
+needs this however.
+
+For ESS chips an additional parameter "esstype" can be specified. This controls
+the (auto) detection of the ESS chips. It can have 3 kinds of values:
+
+-1 Act like 2.0 kernels: only detect ES688 or ES1688.
+0 Try to auto-detect the chip (may fail for ES1688)
+688 The chip will be treated as ES688
+1688 ,, ,, ,, ,, ,, ,, ES1688
+1868 ,, ,, ,, ,, ,, ,, ES1868
+1869 ,, ,, ,, ,, ,, ,, ES1869
+1788 ,, ,, ,, ,, ,, ,, ES1788
+1887 ,, ,, ,, ,, ,, ,, ES1887
+1888 ,, ,, ,, ,, ,, ,, ES1888
+
+Because Full Duplex is supported for ES1887 you can specify a second DMA
+channel by specifying module parameter dma16. It can be one of: 0, 1, 3 or 5.
+
diff --git a/Documentation/sound/oss/ESS1868 b/Documentation/sound/oss/ESS1868
new file mode 100644
index 0000000..55e922f
--- /dev/null
+++ b/Documentation/sound/oss/ESS1868
@@ -0,0 +1,55 @@
+Documentation for the ESS1868F AudioDrive PnP sound card
+
+The ESS1868 sound card is a PnP ESS1688-compatible 16-bit sound card.
+
+It should be automatically detected by the Linux Kernel isapnp support when you
+load the sb.o module. Otherwise you should take care of:
+
+ * The ESS1868 does not allow use of a 16-bit DMA, thus DMA 0, 1, 2, and 3
+ may only be used.
+
+ * isapnptools version 1.14 does work with ESS1868. Earlier versions might
+ not.
+
+ * Sound support MUST be compiled as MODULES, not statically linked
+ into the kernel.
+
+
+NOTE: this is only needed when not using the kernel isapnp support!
+
+For configuring the sound card's I/O addresses, IRQ and DMA, here is a
+sample copy of the isapnp.conf directives regarding the ESS1868:
+
+(CONFIGURE ESS1868/-1 (LD 1
+(IO 0 (BASE 0x0220))
+(IO 1 (BASE 0x0388))
+(IO 2 (BASE 0x0330))
+(DMA 0 (CHANNEL 1))
+(INT 0 (IRQ 5 (MODE +E)))
+(ACT Y)
+))
+
+(for a full working isapnp.conf file, remember the
+(ISOLATE)
+(IDENTIFY *)
+at the beginning and the
+(WAITFORKEY)
+at the end.)
+
+In this setup, the main card I/O is 0x0220, FM synthesizer is 0x0388, and
+the MPU-401 MIDI port is located at 0x0330. IRQ is IRQ 5, DMA is channel 1.
+
+After configuring the sound card via isapnp, to use the card you must load
+the sound modules with the proper I/O information. Here is my setup:
+
+# ESS1868F AudioDrive initialization
+
+/sbin/modprobe sound
+/sbin/insmod uart401
+/sbin/insmod sb io=0x220 irq=5 dma=1 dma16=-1
+/sbin/insmod mpu401 io=0x330
+/sbin/insmod opl3 io=0x388
+/sbin/insmod v_midi
+
+opl3 is the FM synthesizer
+/sbin/insmod opl3 io=0x388
diff --git a/Documentation/sound/oss/Introduction b/Documentation/sound/oss/Introduction
new file mode 100644
index 0000000..f04ba6b
--- /dev/null
+++ b/Documentation/sound/oss/Introduction
@@ -0,0 +1,459 @@
+Introduction Notes on Modular Sound Drivers and Soundcore
+Wade Hampton
+2/14/2001
+
+Purpose:
+========
+This document provides some general notes on the modular
+sound drivers and their configuration, along with the
+support modules sound.o and soundcore.o.
+
+Note, some of this probably should be added to the Sound-HOWTO!
+
+Note, soundlow.o was present with 2.2 kernels but is not
+required for 2.4.x kernels. References have been removed
+to this.
+
+
+Copying:
+========
+none
+
+
+History:
+========
+0.1.0 11/20/1998 First version, draft
+1.0.0 11/1998 Alan Cox changes, incorporation in 2.2.0
+ as Documentation/sound/oss/Introduction
+1.1.0 6/30/1999 Second version, added notes on making the drivers,
+ added info on multiple sound cards of similar types,]
+ added more diagnostics info, added info about esd.
+ added info on OSS and ALSA.
+1.1.1 19991031 Added notes on sound-slot- and sound-service.
+ (Alan Cox)
+1.1.2 20000920 Modified for Kernel 2.4 (Christoph Hellwig)
+1.1.3 20010214 Minor notes and corrections (Wade Hampton)
+ Added examples of sound-slot-0, etc.
+
+
+Modular Sound Drivers:
+======================
+
+Thanks to the GREAT work by Alan Cox (alan@lxorguk.ukuu.org.uk),
+
+[And Oleg Drokin, Thomas Sailer, Andrew Veliath and more than a few
+ others - not to mention Hannu's original code being designed well
+ enough to cope with that kind of chopping up](Alan)
+
+the standard Linux kernels support a modular sound driver. From
+Alan's comments in linux/drivers/sound/README.FIRST:
+
+ The modular sound driver patches were funded by Red Hat Software
+ (www.redhat.com). The sound driver here is thus a modified version of
+ Hannu's code. Please bear that in mind when considering the appropriate
+ forums for bug reporting.
+
+The modular sound drivers may be loaded via insmod or modprobe.
+To support all the various sound modules, there are two general
+support modules that must be loaded first:
+
+ soundcore.o: Top level handler for the sound system, provides
+ a set of functions for registration of devices
+ by type.
+
+ sound.o: Common sound functions required by all modules.
+
+For the specific sound modules (e.g., sb.o for the Soundblaster),
+read the documentation on that module to determine what options
+are available, for example IRQ, address, DMA.
+
+Warning, the options for different cards sometime use different names
+for the same or a similar feature (dma1= versus dma16=). As a last
+resort, inspect the code (search for module_param).
+
+Notes:
+
+1. There is a new OpenSource sound driver called ALSA which is
+ currently under development: http://www.alsa-project.org/
+ The ALSA drivers support some newer hardware that may not
+ be supported by this sound driver and also provide some
+ additional features.
+
+2. The commercial OSS driver may be obtained from the site:
+ http://www/opensound.com. This may be used for cards that
+ are unsupported by the kernel driver, or may be used
+ by other operating systems.
+
+3. The enlightenment sound daemon may be used for playing
+ multiple sounds at the same time via a single card, eliminating
+ some of the requirements for multiple sound card systems. For
+ more information, see: http://www.tux.org/~ricdude/EsounD.html
+ The "esd" program may be used with the real-player and mpeg
+ players like mpg123 and x11amp. The newer real-player
+ and some games even include built-in support for ESD!
+
+
+Building the Modules:
+=====================
+
+This document does not provide full details on building the
+kernel, etc. The notes below apply only to making the kernel
+sound modules. If this conflicts with the kernel's README,
+the README takes precedence.
+
+1. To make the kernel sound modules, cd to your /usr/src/linux
+ directory (typically) and type make config, make menuconfig,
+ or make xconfig (to start the command line, dialog, or x-based
+ configuration tool).
+
+2. Select the Sound option and a dialog will be displayed.
+
+3. Select M (module) for "Sound card support".
+
+4. Select your sound driver(s) as a module. For ProAudio, Sound
+ Blaster, etc., select M (module) for OSS sound modules.
+ [thanks to Marvin Stodolsky <stodolsk@erols.com>]A
+
+5. Make the kernel (e.g., make bzImage), and install the kernel.
+
+6. Make the modules and install them (make modules; make modules_install).
+
+Note, for 2.5.x kernels, make sure you have the newer module-init-tools
+installed or modules will not be loaded properly. 2.5.x requires an
+updated module-init-tools.
+
+
+Plug and Play (PnP:
+===================
+
+If the sound card is an ISA PnP card, isapnp may be used
+to configure the card. See the file isapnp.txt in the
+directory one level up (e.g., /usr/src/linux/Documentation).
+
+Also the 2.4.x kernels provide PnP capabilities, see the
+file NEWS in this directory.
+
+PCI sound cards are highly recommended, as they are far
+easier to configure and from what I have read, they use
+less resources and are more CPU efficient.
+
+
+INSMOD:
+=======
+
+If loading via insmod, the common modules must be loaded in the
+order below BEFORE loading the other sound modules. The card-specific
+modules may then be loaded (most require parameters). For example,
+I use the following via a shell script to load my SoundBlaster:
+
+SB_BASE=0x240
+SB_IRQ=9
+SB_DMA=3
+SB_DMA2=5
+SB_MPU=0x300
+#
+echo Starting sound
+/sbin/insmod soundcore
+/sbin/insmod sound
+#
+echo Starting sound blaster....
+/sbin/insmod uart401
+/sbin/insmod sb io=$SB_BASE irq=$SB_IRQ dma=$SB_DMA dma16=$SB_DMA2 mpu_io=$SB_MP
+
+When using sound as a module, I typically put these commands
+in a file such as /root/soundon.sh.
+
+
+MODPROBE:
+=========
+
+If loading via modprobe, these common files are automatically loaded
+when requested by modprobe. For example, my /etc/modprobe.conf contains:
+
+alias sound sb
+options sb io=0x240 irq=9 dma=3 dma16=5 mpu_io=0x300
+
+All you need to do to load the module is:
+
+ /sbin/modprobe sb
+
+
+Sound Status:
+=============
+
+The status of sound may be read/checked by:
+ cat (anyfile).au >/dev/audio
+
+[WWH: This may not work properly for SoundBlaster PCI 128 cards
+such as the es1370/1 (see the es1370/1 files in this directory)
+as they do not automatically support uLaw on /dev/audio.]
+
+The status of the modules and which modules depend on
+which other modules may be checked by:
+ /sbin/lsmod
+
+/sbin/lsmod should show something like the following:
+ sb 26280 0
+ uart401 5640 0 [sb]
+ sound 57112 0 [sb uart401]
+ soundcore 1968 8 [sb sound]
+
+
+Removing Sound:
+===============
+
+Sound may be removed by using /sbin/rmmod in the reverse order
+in which you load the modules. Note, if a program has a sound device
+open (e.g., xmixer), that module (and the modules on which it
+depends) may not be unloaded.
+
+For example, I use the following to remove my Soundblaster (rmmod
+in the reverse order in which I loaded the modules):
+
+/sbin/rmmod sb
+/sbin/rmmod uart401
+/sbin/rmmod sound
+/sbin/rmmod soundcore
+
+When using sound as a module, I typically put these commands
+in a script such as /root/soundoff.sh.
+
+
+Removing Sound for use with OSS:
+================================
+
+If you get really stuck or have a card that the kernel modules
+will not support, you can get a commercial sound driver from
+http://www.opensound.com. Before loading the commercial sound
+driver, you should do the following:
+
+1. remove sound modules (detailed above)
+2. remove the sound modules from /etc/modprobe.conf
+3. move the sound modules from /lib/modules/<kernel>/misc
+ (for example, I make a /lib/modules/<kernel>/misc/tmp
+ directory and copy the sound module files to that
+ directory).
+
+
+Multiple Sound Cards:
+=====================
+
+The sound drivers will support multiple sound cards and there
+are some great applications like multitrack that support them.
+Typically, you need two sound cards of different types. Note, this
+uses more precious interrupts and DMA channels and sometimes
+can be a configuration nightmare. I have heard reports of 3-4
+sound cards (typically I only use 2). You can sometimes use
+multiple PCI sound cards of the same type.
+
+On my machine I have two sound cards (cs4232 and Soundblaster Vibra
+16). By loading sound as modules, I can control which is the first
+sound device (/dev/dsp, /dev/audio, /dev/mixer) and which is
+the second. Normally, the cs4232 (Dell sound on the motherboard)
+would be the first sound device, but I prefer the Soundblaster.
+All you have to do is to load the one you want as /dev/dsp
+first (in my case "sb") and then load the other one
+(in my case "cs4232").
+
+If you have two cards of the same type that are jumpered
+cards or different PnP revisions, you may load the same
+module twice. For example, I have a SoundBlaster vibra 16
+and an older SoundBlaster 16 (jumpers). To load the module
+twice, you need to do the following:
+
+1. Copy the sound modules to a new name. For example
+ sb.o could be copied (or symlinked) to sb1.o for the
+ second SoundBlaster.
+
+2. Make a second entry in /etc/modprobe.conf, for example,
+ sound1 or sb1. This second entry should refer to the
+ new module names for example sb1, and should include
+ the I/O, etc. for the second sound card.
+
+3. Update your soundon.sh script, etc.
+
+Warning: I have never been able to get two PnP sound cards of the
+same type to load at the same time. I have tried this several times
+with the Soundblaster Vibra 16 cards. OSS has indicated that this
+is a PnP problem.... If anyone has any luck doing this, please
+send me an E-MAIL. PCI sound cards should not have this problem.a
+Since this was originally release, I have received a couple of
+mails from people who have accomplished this!
+
+NOTE: In Linux 2.4 the Sound Blaster driver (and only this one yet)
+supports multiple cards with one module by default.
+Read the file 'Soundblaster' in this directory for details.
+
+
+Sound Problems:
+===============
+
+First RTFM (including the troubleshooting section
+in the Sound-HOWTO).
+
+1) If you are having problems loading the modules (for
+ example, if you get device conflict errors) try the
+ following:
+
+ A) If you have Win95 or NT on the same computer,
+ write down what addresses, IRQ, and DMA channels
+ those were using for the same hardware. You probably
+ can use these addresses, IRQs, and DMA channels.
+ You should really do this BEFORE attempting to get
+ sound working!
+
+ B) Check (cat) /proc/interrupts, /proc/ioports,
+ and /proc/dma. Are you trying to use an address,
+ IRQ or DMA port that another device is using?
+
+ C) Check (cat) /proc/isapnp
+
+ D) Inspect your /var/log/messages file. Often that will
+ indicate what IRQ or IO port could not be obtained.
+
+ E) Try another port or IRQ. Note this may involve
+ using the PnP tools to move the sound card to
+ another location. Sometimes this is the only way
+ and it is more or less trial and error.
+
+2) If you get motor-boating (the same sound or part of a
+ sound clip repeated), you probably have either an IRQ
+ or DMA conflict. Move the card to another IRQ or DMA
+ port. This has happened to me when playing long files
+ when I had an IRQ conflict.
+
+3. If you get dropouts or pauses when playing high sample
+ rate files such as using mpg123 or x11amp/xmms, you may
+ have too slow of a CPU and may have to use the options to
+ play the files at 1/2 speed. For example, you may use
+ the -2 or -4 option on mpg123. You may also get this
+ when trying to play mpeg files stored on a CD-ROM
+ (my Toshiba T8000 PII/366 sometimes has this problem).
+
+4. If you get "cannot access device" errors, your /dev/dsp
+ files, etc. may be set to owner root, mode 600. You
+ may have to use the command:
+ chmod 666 /dev/dsp /dev/mixer /dev/audio
+
+5. If you get "device busy" errors, another program has the
+ sound device open. For example, if using the Enlightenment
+ sound daemon "esd", the "esd" program has the sound device.
+ If using "esd", please RTFM the docs on ESD. For example,
+ esddsp <program> may be used to play files via a non-esd
+ aware program.
+
+6) Ask for help on the sound list or send E-MAIL to the
+ sound driver author/maintainer.
+
+7) Turn on debug in drivers/sound/sound_config.h (DEB, DDB, MDB).
+
+8) If the system reports insufficient DMA memory then you may want to
+ load sound with the "dmabufs=1" option. Or in /etc/conf.modules add
+
+ preinstall sound dmabufs=1
+
+ This makes the sound system allocate its buffers and hang onto them.
+
+ You may also set persistent DMA when building a 2.4.x kernel.
+
+
+Configuring Sound:
+==================
+
+There are several ways of configuring your sound:
+
+1) On the kernel command line (when using the sound driver(s)
+ compiled in the kernel). Check the driver source and
+ documentation for details.
+
+2) On the command line when using insmod or in a bash script
+ using command line calls to load sound.
+
+3) In /etc/modprobe.conf when using modprobe.
+
+4) Via Red Hat's GPL'd /usr/sbin/sndconfig program (text based).
+
+5) Via the OSS soundconf program (with the commercial version
+ of the OSS driver.
+
+6) By just loading the module and let isapnp do everything relevant
+ for you. This works only with a few drivers yet and - of course -
+ only with isapnp hardware.
+
+And I am sure, several other ways.
+
+Anyone want to write a linuxconf module for configuring sound?
+
+
+Module Loading:
+===============
+
+When a sound card is first referenced and sound is modular, the sound system
+will ask for the sound devices to be loaded. Initially it requests that
+the driver for the sound system is loaded. It then will ask for
+sound-slot-0, where 0 is the first sound card. (sound-slot-1 the second and
+so on). Thus you can do
+
+alias sound-slot-0 sb
+
+To load a soundblaster at this point. If the slot loading does not provide
+the desired device - for example a soundblaster does not directly provide
+a midi synth in all cases then it will request "sound-service-0-n" where n
+is
+
+ 0 Mixer
+
+ 2 MIDI
+
+ 3, 4 DSP audio
+
+
+For example, I use the following to load my Soundblaster PCI 128
+(ES 1371) card first, followed by my SoundBlaster Vibra 16 card,
+then by my TV card:
+
+# Load the Soundblaster PCI 128 as /dev/dsp, /dev/dsp1, /dev/mixer
+alias sound-slot-0 es1371
+
+# Load the Soundblaster Vibra 16 as /dev/dsp2, /dev/mixer1
+alias sound-slot-1 sb
+options sb io=0x240 irq=5 dma=1 dma16=5 mpu_io=0x330
+
+# Load the BTTV (TV card) as /dev/mixer2
+alias sound-slot-2 bttv
+alias sound-service-2-0 tvmixer
+
+pre-install bttv modprobe tuner ; modprobe tvmixer
+pre-install tvmixer modprobe msp3400; modprobe tvaudio
+options tuner debug=0 type=8
+options bttv card=0 radio=0 pll=0
+
+
+For More Information (RTFM):
+============================
+1) Information on kernel modules: manual pages for insmod and modprobe.
+
+2) Information on PnP, RTFM manual pages for isapnp.
+
+3) Sound-HOWTO and Sound-Playing-HOWTO.
+
+4) OSS's WWW site at http://www.opensound.com.
+
+5) All the files in Documentation/sound.
+
+6) The comments and code in linux/drivers/sound.
+
+7) The sndconfig and rhsound documentation from Red Hat.
+
+8) The Linux-sound mailing list: sound-list@redhat.com.
+
+9) Enlightenment documentation (for info on esd)
+ http://www.tux.org/~ricdude/EsounD.html.
+
+10) ALSA home page: http://www.alsa-project.org/
+
+
+Contact Information:
+====================
+Wade Hampton: (whampton@staffnet.com)
+
diff --git a/Documentation/sound/oss/MultiSound b/Documentation/sound/oss/MultiSound
new file mode 100644
index 0000000..e4a18bb
--- /dev/null
+++ b/Documentation/sound/oss/MultiSound
@@ -0,0 +1,1137 @@
+#! /bin/sh
+#
+# Turtle Beach MultiSound Driver Notes
+# -- Andrew Veliath <andrewtv@usa.net>
+#
+# Last update: September 10, 1998
+# Corresponding msnd driver: 0.8.3
+#
+# ** This file is a README (top part) and shell archive (bottom part).
+# The corresponding archived utility sources can be unpacked by
+# running `sh MultiSound' (the utilities are only needed for the
+# Pinnacle and Fiji cards). **
+#
+#
+# -=-=- Getting Firmware -=-=-
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# See the section `Obtaining and Creating Firmware Files' in this
+# document for instructions on obtaining the necessary firmware
+# files.
+#
+#
+# Supported Features
+# ~~~~~~~~~~~~~~~~~~
+#
+# Currently, full-duplex digital audio (/dev/dsp only, /dev/audio is
+# not currently available) and mixer functionality (/dev/mixer) are
+# supported (memory mapped digital audio is not yet supported).
+# Digital transfers and monitoring can be done as well if you have
+# the digital daughterboard (see the section on using the S/PDIF port
+# for more information).
+#
+# Support for the Turtle Beach MultiSound Hurricane architecture is
+# composed of the following modules (these can also operate compiled
+# into the kernel):
+#
+# msnd - MultiSound base (requires soundcore)
+#
+# msnd_classic - Base audio/mixer support for Classic, Monetery and
+# Tahiti cards
+#
+# msnd_pinnacle - Base audio/mixer support for Pinnacle and Fiji cards
+#
+#
+# Important Notes - Read Before Using
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# The firmware files are not included (may change in future). You
+# must obtain these images from Turtle Beach (they are included in
+# the MultiSound Development Kits), and place them in /etc/sound for
+# example, and give the full paths in the Linux configuration. If
+# you are compiling in support for the MultiSound driver rather than
+# using it as a module, these firmware files must be accessible
+# during kernel compilation.
+#
+# Please note these files must be binary files, not assembler. See
+# the section later in this document for instructions to obtain these
+# files.
+#
+#
+# Configuring Card Resources
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# ** This section is very important, as your card may not work at all
+# or your machine may crash if you do not do this correctly. **
+#
+# * Classic/Monterey/Tahiti
+#
+# These cards are configured through the driver msnd_classic. You must
+# know the io port, then the driver will select the irq and memory resources
+# on the card. It is up to you to know if these are free locations or now,
+# a conflict can lock the machine up.
+#
+# * Pinnacle/Fiji
+#
+# The Pinnacle and Fiji cards have an extra config port, either
+# 0x250, 0x260 or 0x270. This port can be disabled to have the card
+# configured strictly through PnP, however you lose the ability to
+# access the IDE controller and joystick devices on this card when
+# using PnP. The included pinnaclecfg program in this shell archive
+# can be used to configure the card in non-PnP mode, and in PnP mode
+# you can use isapnptools. These are described briefly here.
+#
+# pinnaclecfg is not required; you can use the msnd_pinnacle module
+# to fully configure the card as well. However, pinnaclecfg can be
+# used to change the resource values of a particular device after the
+# msnd_pinnacle module has been loaded. If you are compiling the
+# driver into the kernel, you must set these values during compile
+# time, however other peripheral resource values can be changed with
+# the pinnaclecfg program after the kernel is loaded.
+#
+#
+# *** PnP mode
+#
+# Use pnpdump to obtain a sample configuration if you can; I was able
+# to obtain one with the command `pnpdump 1 0x203' -- this may vary
+# for you (running pnpdump by itself did not work for me). Then,
+# edit this file and use isapnp to uncomment and set the card values.
+# Use these values when inserting the msnd_pinnacle module. Using
+# this method, you can set the resources for the DSP and the Kurzweil
+# synth (Pinnacle). Since Linux does not directly support PnP
+# devices, you may have difficulty when using the card in PnP mode
+# when it the driver is compiled into the kernel. Using non-PnP mode
+# is preferable in this case.
+#
+# Here is an example mypinnacle.conf for isapnp that sets the card to
+# io base 0x210, irq 5 and mem 0xd8000, and also sets the Kurzweil
+# synth to 0x330 and irq 9 (may need editing for your system):
+#
+# (READPORT 0x0203)
+# (CSN 2)
+# (IDENTIFY *)
+#
+# # DSP
+# (CONFIGURE BVJ0440/-1 (LD 0
+# (INT 0 (IRQ 5 (MODE +E))) (IO 0 (BASE 0x0210)) (MEM 0 (BASE 0x0d8000))
+# (ACT Y)))
+#
+# # Kurzweil Synth (Pinnacle Only)
+# (CONFIGURE BVJ0440/-1 (LD 1
+# (IO 0 (BASE 0x0330)) (INT 0 (IRQ 9 (MODE +E)))
+# (ACT Y)))
+#
+# (WAITFORKEY)
+#
+#
+# *** Non-PnP mode
+#
+# The second way is by running the card in non-PnP mode. This
+# actually has some advantages in that you can access some other
+# devices on the card, such as the joystick and IDE controller. To
+# configure the card, unpack this shell archive and build the
+# pinnaclecfg program. Using this program, you can assign the
+# resource values to the card's devices, or disable the devices. As
+# an alternative to using pinnaclecfg, you can specify many of the
+# configuration values when loading the msnd_pinnacle module (or
+# during kernel configuration when compiling the driver into the
+# kernel).
+#
+# If you specify cfg=0x250 for the msnd_pinnacle module, it
+# automatically configure the card to the given io, irq and memory
+# values using that config port (the config port is jumper selectable
+# on the card to 0x250, 0x260 or 0x270).
+#
+# See the `msnd_pinnacle Additional Options' section below for more
+# information on these parameters (also, if you compile the driver
+# directly into the kernel, these extra parameters can be useful
+# here).
+#
+#
+# ** It is very easy to cause problems in your machine if you choose a
+# resource value which is incorrect. **
+#
+#
+# Examples
+# ~~~~~~~~
+#
+# * MultiSound Classic/Monterey/Tahiti:
+#
+# modprobe soundcore
+# insmod msnd
+# insmod msnd_classic io=0x290 irq=7 mem=0xd0000
+#
+# * MultiSound Pinnacle in PnP mode:
+#
+# modprobe soundcore
+# insmod msnd
+# isapnp mypinnacle.conf
+# insmod msnd_pinnacle io=0x210 irq=5 mem=0xd8000 <-- match mypinnacle.conf values
+#
+# * MultiSound Pinnacle in non-PnP mode (replace 0x250 with your configuration port,
+# one of 0x250, 0x260 or 0x270):
+#
+# insmod soundcore
+# insmod msnd
+# insmod msnd_pinnacle cfg=0x250 io=0x290 irq=5 mem=0xd0000
+#
+# * To use the MPU-compatible Kurzweil synth on the Pinnacle in PnP
+# mode, add the following (assumes you did `isapnp mypinnacle.conf'):
+#
+# insmod sound
+# insmod mpu401 io=0x330 irq=9 <-- match mypinnacle.conf values
+#
+# * To use the MPU-compatible Kurzweil synth on the Pinnacle in non-PnP
+# mode, add the following. Note how we first configure the peripheral's
+# resources, _then_ install a Linux driver for it:
+#
+# insmod sound
+# pinnaclecfg 0x250 mpu 0x330 9
+# insmod mpu401 io=0x330 irq=9
+#
+# -- OR you can use the following sequence without pinnaclecfg in non-PnP mode:
+#
+# insmod soundcore
+# insmod msnd
+# insmod msnd_pinnacle cfg=0x250 io=0x290 irq=5 mem=0xd0000 mpu_io=0x330 mpu_irq=9
+# insmod sound
+# insmod mpu401 io=0x330 irq=9
+#
+# * To setup the joystick port on the Pinnacle in non-PnP mode (though
+# you have to find the actual Linux joystick driver elsewhere), you
+# can use pinnaclecfg:
+#
+# pinnaclecfg 0x250 joystick 0x200
+#
+# -- OR you can configure this using msnd_pinnacle with the following:
+#
+# insmod soundcore
+# insmod msnd
+# insmod msnd_pinnacle cfg=0x250 io=0x290 irq=5 mem=0xd0000 joystick_io=0x200
+#
+#
+# msnd_classic, msnd_pinnacle Required Options
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# If the following options are not given, the module will not load.
+# Examine the kernel message log for informative error messages.
+# WARNING--probing isn't supported so try to make sure you have the
+# correct shared memory area, otherwise you may experience problems.
+#
+# io I/O base of DSP, e.g. io=0x210
+# irq IRQ number, e.g. irq=5
+# mem Shared memory area, e.g. mem=0xd8000
+#
+#
+# msnd_classic, msnd_pinnacle Additional Options
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# fifosize The digital audio FIFOs, in kilobytes. If not
+# specified, the default will be used. Increasing
+# this value will reduce the chance of a FIFO
+# underflow at the expense of increasing overall
+# latency. For example, fifosize=512 will
+# allocate 512kB read and write FIFOs (1MB total).
+# While this may reduce dropouts, a heavy machine
+# load will undoubtedly starve the FIFO of data
+# and you will eventually get dropouts. One
+# option is to alter the scheduling priority of
+# the playback process, using `nice' or some form
+# of POSIX soft real-time scheduling.
+#
+# calibrate_signal Setting this to one calibrates the ADCs to the
+# signal, zero calibrates to the card (defaults
+# to zero).
+#
+#
+# msnd_pinnacle Additional Options
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# digital Specify digital=1 to enable the S/PDIF input
+# if you have the digital daughterboard
+# adapter. This will enable access to the
+# DIGITAL1 input for the soundcard in the mixer.
+# Some mixer programs might have trouble setting
+# the DIGITAL1 source as an input. If you have
+# trouble, you can try the setdigital.c program
+# at the bottom of this document.
+#
+# cfg Non-PnP configuration port for the Pinnacle
+# and Fiji (typically 0x250, 0x260 or 0x270,
+# depending on the jumper configuration). If
+# this option is omitted, then it is assumed
+# that the card is in PnP mode, and that the
+# specified DSP resource values are already
+# configured with PnP (i.e. it won't attempt to
+# do any sort of configuration).
+#
+# When the Pinnacle is in non-PnP mode, you can use the following
+# options to configure particular devices. If a full specification
+# for a device is not given, then the device is not configured. Note
+# that you still must use a Linux driver for any of these devices
+# once their resources are setup (such as the Linux joystick driver,
+# or the MPU401 driver from OSS for the Kurzweil synth).
+#
+# mpu_io I/O port of MPU (on-board Kurzweil synth)
+# mpu_irq IRQ of MPU (on-board Kurzweil synth)
+# ide_io0 First I/O port of IDE controller
+# ide_io1 Second I/O port of IDE controller
+# ide_irq IRQ IDE controller
+# joystick_io I/O port of joystick
+#
+#
+# Obtaining and Creating Firmware Files
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# For the Classic/Tahiti/Monterey
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# Download to /tmp and unzip the following file from Turtle Beach:
+#
+# ftp://ftp.voyetra.com/pub/tbs/msndcl/msndvkit.zip
+#
+# When unzipped, unzip the file named MsndFiles.zip. Then copy the
+# following firmware files to /etc/sound (note the file renaming):
+#
+# cp DSPCODE/MSNDINIT.BIN /etc/sound/msndinit.bin
+# cp DSPCODE/MSNDPERM.REB /etc/sound/msndperm.bin
+#
+# When configuring the Linux kernel, specify /etc/sound/msndinit.bin and
+# /etc/sound/msndperm.bin for the two firmware files (Linux kernel
+# versions older than 2.2 do not ask for firmware paths, and are
+# hardcoded to /etc/sound).
+#
+# If you are compiling the driver into the kernel, these files must
+# be accessible during compilation, but will not be needed later.
+# The files must remain, however, if the driver is used as a module.
+#
+#
+# For the Pinnacle/Fiji
+# ~~~~~~~~~~~~~~~~~~~~~
+#
+# Download to /tmp and unzip the following file from Turtle Beach (be
+# sure to use the entire URL; some have had trouble navigating to the
+# URL):
+#
+# ftp://ftp.voyetra.com/pub/tbs/pinn/pnddk100.zip
+#
+# Unpack this shell archive, and run make in the created directory
+# (you need a C compiler and flex to build the utilities). This
+# should give you the executables conv, pinnaclecfg and setdigital.
+# conv is only used temporarily here to create the firmware files,
+# while pinnaclecfg is used to configure the Pinnacle or Fiji card in
+# non-PnP mode, and setdigital can be used to set the S/PDIF input on
+# the mixer (pinnaclecfg and setdigital should be copied to a
+# convenient place, possibly run during system initialization).
+#
+# To generating the firmware files with the `conv' program, we create
+# the binary firmware files by doing the following conversion
+# (assuming the archive unpacked into a directory named PINNDDK):
+#
+# ./conv < PINNDDK/dspcode/pndspini.asm > /etc/sound/pndspini.bin
+# ./conv < PINNDDK/dspcode/pndsperm.asm > /etc/sound/pndsperm.bin
+#
+# The conv (and conv.l) program is not needed after conversion and can
+# be safely deleted. Then, when configuring the Linux kernel, specify
+# /etc/sound/pndspini.bin and /etc/sound/pndsperm.bin for the two
+# firmware files (Linux kernel versions older than 2.2 do not ask for
+# firmware paths, and are hardcoded to /etc/sound).
+#
+# If you are compiling the driver into the kernel, these files must
+# be accessible during compilation, but will not be needed later.
+# The files must remain, however, if the driver is used as a module.
+#
+#
+# Using Digital I/O with the S/PDIF Port
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# If you have a Pinnacle or Fiji with the digital daughterboard and
+# want to set it as the input source, you can use this program if you
+# have trouble trying to do it with a mixer program (be sure to
+# insert the module with the digital=1 option, or say Y to the option
+# during compiled-in kernel operation). Upon selection of the S/PDIF
+# port, you should be able monitor and record from it.
+#
+# There is something to note about using the S/PDIF port. Digital
+# timing is taken from the digital signal, so if a signal is not
+# connected to the port and it is selected as recording input, you
+# will find PCM playback to be distorted in playback rate. Also,
+# attempting to record at a sampling rate other than the DAT rate may
+# be problematic (i.e. trying to record at 8000Hz when the DAT signal
+# is 44100Hz). If you have a problem with this, set the recording
+# input to analog if you need to record at a rate other than that of
+# the DAT rate.
+#
+#
+# -- Shell archive attached below, just run `sh MultiSound' to extract.
+# Contains Pinnacle/Fiji utilities to convert firmware, configure
+# in non-PnP mode, and select the DIGITAL1 input for the mixer.
+#
+#
+#!/bin/sh
+# This is a shell archive (produced by GNU sharutils 4.2).
+# To extract the files from this archive, save it to some FILE, remove
+# everything before the `!/bin/sh' line above, then type `sh FILE'.
+#
+# Made on 1998-12-04 10:07 EST by <andrewtv@ztransform.velsoft.com>.
+# Source directory was `/home/andrewtv/programming/pinnacle/pinnacle'.
+#
+# Existing files will *not* be overwritten unless `-c' is specified.
+#
+# This shar contains:
+# length mode name
+# ------ ---------- ------------------------------------------
+# 2046 -rw-rw-r-- MultiSound.d/setdigital.c
+# 10235 -rw-rw-r-- MultiSound.d/pinnaclecfg.c
+# 106 -rw-rw-r-- MultiSound.d/Makefile
+# 141 -rw-rw-r-- MultiSound.d/conv.l
+# 1472 -rw-rw-r-- MultiSound.d/msndreset.c
+#
+save_IFS="${IFS}"
+IFS="${IFS}:"
+gettext_dir=FAILED
+locale_dir=FAILED
+first_param="$1"
+for dir in $PATH
+do
+ if test "$gettext_dir" = FAILED && test -f $dir/gettext \
+ && ($dir/gettext --version >/dev/null 2>&1)
+ then
+ set `$dir/gettext --version 2>&1`
+ if test "$3" = GNU
+ then
+ gettext_dir=$dir
+ fi
+ fi
+ if test "$locale_dir" = FAILED && test -f $dir/shar \
+ && ($dir/shar --print-text-domain-dir >/dev/null 2>&1)
+ then
+ locale_dir=`$dir/shar --print-text-domain-dir`
+ fi
+done
+IFS="$save_IFS"
+if test "$locale_dir" = FAILED || test "$gettext_dir" = FAILED
+then
+ echo=echo
+else
+ TEXTDOMAINDIR=$locale_dir
+ export TEXTDOMAINDIR
+ TEXTDOMAIN=sharutils
+ export TEXTDOMAIN
+ echo="$gettext_dir/gettext -s"
+fi
+touch -am 1231235999 $$.touch >/dev/null 2>&1
+if test ! -f 1231235999 && test -f $$.touch; then
+ shar_touch=touch
+else
+ shar_touch=:
+ echo
+ $echo 'WARNING: not restoring timestamps. Consider getting and'
+ $echo "installing GNU \`touch', distributed in GNU File Utilities..."
+ echo
+fi
+rm -f 1231235999 $$.touch
+#
+if mkdir _sh01426; then
+ $echo 'x -' 'creating lock directory'
+else
+ $echo 'failed to create lock directory'
+ exit 1
+fi
+# ============= MultiSound.d/setdigital.c ==============
+if test ! -d 'MultiSound.d'; then
+ $echo 'x -' 'creating directory' 'MultiSound.d'
+ mkdir 'MultiSound.d'
+fi
+if test -f 'MultiSound.d/setdigital.c' && test "$first_param" != -c; then
+ $echo 'x -' SKIPPING 'MultiSound.d/setdigital.c' '(file already exists)'
+else
+ $echo 'x -' extracting 'MultiSound.d/setdigital.c' '(text)'
+ sed 's/^X//' << 'SHAR_EOF' > 'MultiSound.d/setdigital.c' &&
+/*********************************************************************
+X *
+X * setdigital.c - sets the DIGITAL1 input for a mixer
+X *
+X * Copyright (C) 1998 Andrew Veliath
+X *
+X * This program is free software; you can redistribute it and/or modify
+X * it under the terms of the GNU General Public License as published by
+X * the Free Software Foundation; either version 2 of the License, or
+X * (at your option) any later version.
+X *
+X * This program is distributed in the hope that it will be useful,
+X * but WITHOUT ANY WARRANTY; without even the implied warranty of
+X * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+X * GNU General Public License for more details.
+X *
+X * You should have received a copy of the GNU General Public License
+X * along with this program; if not, write to the Free Software
+X * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+X *
+X ********************************************************************/
+X
+#include <stdio.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <sys/ioctl.h>
+#include <sys/soundcard.h>
+X
+int main(int argc, char *argv[])
+{
+X int fd;
+X unsigned long recmask, recsrc;
+X
+X if (argc != 2) {
+X fprintf(stderr, "usage: setdigital <mixer device>\n");
+X exit(1);
+X }
+X
+X if ((fd = open(argv[1], O_RDWR)) < 0) {
+X perror(argv[1]);
+X exit(1);
+X }
+X
+X if (ioctl(fd, SOUND_MIXER_READ_RECMASK, &recmask) < 0) {
+X fprintf(stderr, "error: ioctl read recording mask failed\n");
+X perror("ioctl");
+X close(fd);
+X exit(1);
+X }
+X
+X if (!(recmask & SOUND_MASK_DIGITAL1)) {
+X fprintf(stderr, "error: cannot find DIGITAL1 device in mixer\n");
+X close(fd);
+X exit(1);
+X }
+X
+X if (ioctl(fd, SOUND_MIXER_READ_RECSRC, &recsrc) < 0) {
+X fprintf(stderr, "error: ioctl read recording source failed\n");
+X perror("ioctl");
+X close(fd);
+X exit(1);
+X }
+X
+X recsrc |= SOUND_MASK_DIGITAL1;
+X
+X if (ioctl(fd, SOUND_MIXER_WRITE_RECSRC, &recsrc) < 0) {
+X fprintf(stderr, "error: ioctl write recording source failed\n");
+X perror("ioctl");
+X close(fd);
+X exit(1);
+X }
+X
+X close(fd);
+X
+X return 0;
+}
+SHAR_EOF
+ $shar_touch -am 1204092598 'MultiSound.d/setdigital.c' &&
+ chmod 0664 'MultiSound.d/setdigital.c' ||
+ $echo 'restore of' 'MultiSound.d/setdigital.c' 'failed'
+ if ( md5sum --help 2>&1 | grep 'sage: md5sum \[' ) >/dev/null 2>&1 \
+ && ( md5sum --version 2>&1 | grep -v 'textutils 1.12' ) >/dev/null; then
+ md5sum -c << SHAR_EOF >/dev/null 2>&1 \
+ || $echo 'MultiSound.d/setdigital.c:' 'MD5 check failed'
+e87217fc3e71288102ba41fd81f71ec4 MultiSound.d/setdigital.c
+SHAR_EOF
+ else
+ shar_count="`LC_ALL= LC_CTYPE= LANG= wc -c < 'MultiSound.d/setdigital.c'`"
+ test 2046 -eq "$shar_count" ||
+ $echo 'MultiSound.d/setdigital.c:' 'original size' '2046,' 'current size' "$shar_count!"
+ fi
+fi
+# ============= MultiSound.d/pinnaclecfg.c ==============
+if test -f 'MultiSound.d/pinnaclecfg.c' && test "$first_param" != -c; then
+ $echo 'x -' SKIPPING 'MultiSound.d/pinnaclecfg.c' '(file already exists)'
+else
+ $echo 'x -' extracting 'MultiSound.d/pinnaclecfg.c' '(text)'
+ sed 's/^X//' << 'SHAR_EOF' > 'MultiSound.d/pinnaclecfg.c' &&
+/*********************************************************************
+X *
+X * pinnaclecfg.c - Pinnacle/Fiji Device Configuration Program
+X *
+X * This is for NON-PnP mode only. For PnP mode, use isapnptools.
+X *
+X * This is Linux-specific, and must be run with root permissions.
+X *
+X * Part of the Turtle Beach MultiSound Sound Card Driver for Linux
+X *
+X * Copyright (C) 1998 Andrew Veliath
+X *
+X * This program is free software; you can redistribute it and/or modify
+X * it under the terms of the GNU General Public License as published by
+X * the Free Software Foundation; either version 2 of the License, or
+X * (at your option) any later version.
+X *
+X * This program is distributed in the hope that it will be useful,
+X * but WITHOUT ANY WARRANTY; without even the implied warranty of
+X * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+X * GNU General Public License for more details.
+X *
+X * You should have received a copy of the GNU General Public License
+X * along with this program; if not, write to the Free Software
+X * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+X *
+X ********************************************************************/
+X
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <errno.h>
+#include <unistd.h>
+#include <asm/io.h>
+#include <asm/types.h>
+X
+#define IREG_LOGDEVICE 0x07
+#define IREG_ACTIVATE 0x30
+#define LD_ACTIVATE 0x01
+#define LD_DISACTIVATE 0x00
+#define IREG_EECONTROL 0x3F
+#define IREG_MEMBASEHI 0x40
+#define IREG_MEMBASELO 0x41
+#define IREG_MEMCONTROL 0x42
+#define IREG_MEMRANGEHI 0x43
+#define IREG_MEMRANGELO 0x44
+#define MEMTYPE_8BIT 0x00
+#define MEMTYPE_16BIT 0x02
+#define MEMTYPE_RANGE 0x00
+#define MEMTYPE_HIADDR 0x01
+#define IREG_IO0_BASEHI 0x60
+#define IREG_IO0_BASELO 0x61
+#define IREG_IO1_BASEHI 0x62
+#define IREG_IO1_BASELO 0x63
+#define IREG_IRQ_NUMBER 0x70
+#define IREG_IRQ_TYPE 0x71
+#define IRQTYPE_HIGH 0x02
+#define IRQTYPE_LOW 0x00
+#define IRQTYPE_LEVEL 0x01
+#define IRQTYPE_EDGE 0x00
+X
+#define HIBYTE(w) ((BYTE)(((WORD)(w) >> 8) & 0xFF))
+#define LOBYTE(w) ((BYTE)(w))
+#define MAKEWORD(low,hi) ((WORD)(((BYTE)(low))|(((WORD)((BYTE)(hi)))<<8)))
+X
+typedef __u8 BYTE;
+typedef __u16 USHORT;
+typedef __u16 WORD;
+X
+static int config_port = -1;
+X
+static int msnd_write_cfg(int cfg, int reg, int value)
+{
+X outb(reg, cfg);
+X outb(value, cfg + 1);
+X if (value != inb(cfg + 1)) {
+X fprintf(stderr, "error: msnd_write_cfg: I/O error\n");
+X return -EIO;
+X }
+X return 0;
+}
+X
+static int msnd_read_cfg(int cfg, int reg)
+{
+X outb(reg, cfg);
+X return inb(cfg + 1);
+}
+X
+static int msnd_write_cfg_io0(int cfg, int num, WORD io)
+{
+X if (msnd_write_cfg(cfg, IREG_LOGDEVICE, num))
+X return -EIO;
+X if (msnd_write_cfg(cfg, IREG_IO0_BASEHI, HIBYTE(io)))
+X return -EIO;
+X if (msnd_write_cfg(cfg, IREG_IO0_BASELO, LOBYTE(io)))
+X return -EIO;
+X return 0;
+}
+X
+static int msnd_read_cfg_io0(int cfg, int num, WORD *io)
+{
+X if (msnd_write_cfg(cfg, IREG_LOGDEVICE, num))
+X return -EIO;
+X
+X *io = MAKEWORD(msnd_read_cfg(cfg, IREG_IO0_BASELO),
+X msnd_read_cfg(cfg, IREG_IO0_BASEHI));
+X
+X return 0;
+}
+X
+static int msnd_write_cfg_io1(int cfg, int num, WORD io)
+{
+X if (msnd_write_cfg(cfg, IREG_LOGDEVICE, num))
+X return -EIO;
+X if (msnd_write_cfg(cfg, IREG_IO1_BASEHI, HIBYTE(io)))
+X return -EIO;
+X if (msnd_write_cfg(cfg, IREG_IO1_BASELO, LOBYTE(io)))
+X return -EIO;
+X return 0;
+}
+X
+static int msnd_read_cfg_io1(int cfg, int num, WORD *io)
+{
+X if (msnd_write_cfg(cfg, IREG_LOGDEVICE, num))
+X return -EIO;
+X
+X *io = MAKEWORD(msnd_read_cfg(cfg, IREG_IO1_BASELO),
+X msnd_read_cfg(cfg, IREG_IO1_BASEHI));
+X
+X return 0;
+}
+X
+static int msnd_write_cfg_irq(int cfg, int num, WORD irq)
+{
+X if (msnd_write_cfg(cfg, IREG_LOGDEVICE, num))
+X return -EIO;
+X if (msnd_write_cfg(cfg, IREG_IRQ_NUMBER, LOBYTE(irq)))
+X return -EIO;
+X if (msnd_write_cfg(cfg, IREG_IRQ_TYPE, IRQTYPE_EDGE))
+X return -EIO;
+X return 0;
+}
+X
+static int msnd_read_cfg_irq(int cfg, int num, WORD *irq)
+{
+X if (msnd_write_cfg(cfg, IREG_LOGDEVICE, num))
+X return -EIO;
+X
+X *irq = msnd_read_cfg(cfg, IREG_IRQ_NUMBER);
+X
+X return 0;
+}
+X
+static int msnd_write_cfg_mem(int cfg, int num, int mem)
+{
+X WORD wmem;
+X
+X mem >>= 8;
+X mem &= 0xfff;
+X wmem = (WORD)mem;
+X if (msnd_write_cfg(cfg, IREG_LOGDEVICE, num))
+X return -EIO;
+X if (msnd_write_cfg(cfg, IREG_MEMBASEHI, HIBYTE(wmem)))
+X return -EIO;
+X if (msnd_write_cfg(cfg, IREG_MEMBASELO, LOBYTE(wmem)))
+X return -EIO;
+X if (wmem && msnd_write_cfg(cfg, IREG_MEMCONTROL, (MEMTYPE_HIADDR | MEMTYPE_16BIT)))
+X return -EIO;
+X return 0;
+}
+X
+static int msnd_read_cfg_mem(int cfg, int num, int *mem)
+{
+X if (msnd_write_cfg(cfg, IREG_LOGDEVICE, num))
+X return -EIO;
+X
+X *mem = MAKEWORD(msnd_read_cfg(cfg, IREG_MEMBASELO),
+X msnd_read_cfg(cfg, IREG_MEMBASEHI));
+X *mem <<= 8;
+X
+X return 0;
+}
+X
+static int msnd_activate_logical(int cfg, int num)
+{
+X if (msnd_write_cfg(cfg, IREG_LOGDEVICE, num))
+X return -EIO;
+X if (msnd_write_cfg(cfg, IREG_ACTIVATE, LD_ACTIVATE))
+X return -EIO;
+X return 0;
+}
+X
+static int msnd_write_cfg_logical(int cfg, int num, WORD io0, WORD io1, WORD irq, int mem)
+{
+X if (msnd_write_cfg(cfg, IREG_LOGDEVICE, num))
+X return -EIO;
+X if (msnd_write_cfg_io0(cfg, num, io0))
+X return -EIO;
+X if (msnd_write_cfg_io1(cfg, num, io1))
+X return -EIO;
+X if (msnd_write_cfg_irq(cfg, num, irq))
+X return -EIO;
+X if (msnd_write_cfg_mem(cfg, num, mem))
+X return -EIO;
+X if (msnd_activate_logical(cfg, num))
+X return -EIO;
+X return 0;
+}
+X
+static int msnd_read_cfg_logical(int cfg, int num, WORD *io0, WORD *io1, WORD *irq, int *mem)
+{
+X if (msnd_write_cfg(cfg, IREG_LOGDEVICE, num))
+X return -EIO;
+X if (msnd_read_cfg_io0(cfg, num, io0))
+X return -EIO;
+X if (msnd_read_cfg_io1(cfg, num, io1))
+X return -EIO;
+X if (msnd_read_cfg_irq(cfg, num, irq))
+X return -EIO;
+X if (msnd_read_cfg_mem(cfg, num, mem))
+X return -EIO;
+X return 0;
+}
+X
+static void usage(void)
+{
+X fprintf(stderr,
+X "\n"
+X "pinnaclecfg 1.0\n"
+X "\n"
+X "usage: pinnaclecfg <config port> [device config]\n"
+X "\n"
+X "This is for use with the card in NON-PnP mode only.\n"
+X "\n"
+X "Available devices (not all available for Fiji):\n"
+X "\n"
+X " Device Description\n"
+X " -------------------------------------------------------------------\n"
+X " reset Reset all devices (i.e. disable)\n"
+X " show Display current device configurations\n"
+X "\n"
+X " dsp <io> <irq> <mem> Audio device\n"
+X " mpu <io> <irq> Internal Kurzweil synth\n"
+X " ide <io0> <io1> <irq> On-board IDE controller\n"
+X " joystick <io> Joystick port\n"
+X "\n");
+X exit(1);
+}
+X
+static int cfg_reset(void)
+{
+X int i;
+X
+X for (i = 0; i < 4; ++i)
+X msnd_write_cfg_logical(config_port, i, 0, 0, 0, 0);
+X
+X return 0;
+}
+X
+static int cfg_show(void)
+{
+X int i;
+X int count = 0;
+X
+X for (i = 0; i < 4; ++i) {
+X WORD io0, io1, irq;
+X int mem;
+X msnd_read_cfg_logical(config_port, i, &io0, &io1, &irq, &mem);
+X switch (i) {
+X case 0:
+X if (io0 || irq || mem) {
+X printf("dsp 0x%x %d 0x%x\n", io0, irq, mem);
+X ++count;
+X }
+X break;
+X case 1:
+X if (io0 || irq) {
+X printf("mpu 0x%x %d\n", io0, irq);
+X ++count;
+X }
+X break;
+X case 2:
+X if (io0 || io1 || irq) {
+X printf("ide 0x%x 0x%x %d\n", io0, io1, irq);
+X ++count;
+X }
+X break;
+X case 3:
+X if (io0) {
+X printf("joystick 0x%x\n", io0);
+X ++count;
+X }
+X break;
+X }
+X }
+X
+X if (count == 0)
+X fprintf(stderr, "no devices configured\n");
+X
+X return 0;
+}
+X
+static int cfg_dsp(int argc, char *argv[])
+{
+X int io, irq, mem;
+X
+X if (argc < 3 ||
+X sscanf(argv[0], "0x%x", &io) != 1 ||
+X sscanf(argv[1], "%d", &irq) != 1 ||
+X sscanf(argv[2], "0x%x", &mem) != 1)
+X usage();
+X
+X if (!(io == 0x290 ||
+X io == 0x260 ||
+X io == 0x250 ||
+X io == 0x240 ||
+X io == 0x230 ||
+X io == 0x220 ||
+X io == 0x210 ||
+X io == 0x3e0)) {
+X fprintf(stderr, "error: io must be one of "
+X "210, 220, 230, 240, 250, 260, 290, or 3E0\n");
+X usage();
+X }
+X
+X if (!(irq == 5 ||
+X irq == 7 ||
+X irq == 9 ||
+X irq == 10 ||
+X irq == 11 ||
+X irq == 12)) {
+X fprintf(stderr, "error: irq must be one of "
+X "5, 7, 9, 10, 11 or 12\n");
+X usage();
+X }
+X
+X if (!(mem == 0xb0000 ||
+X mem == 0xc8000 ||
+X mem == 0xd0000 ||
+X mem == 0xd8000 ||
+X mem == 0xe0000 ||
+X mem == 0xe8000)) {
+X fprintf(stderr, "error: mem must be one of "
+X "0xb0000, 0xc8000, 0xd0000, 0xd8000, 0xe0000 or 0xe8000\n");
+X usage();
+X }
+X
+X return msnd_write_cfg_logical(config_port, 0, io, 0, irq, mem);
+}
+X
+static int cfg_mpu(int argc, char *argv[])
+{
+X int io, irq;
+X
+X if (argc < 2 ||
+X sscanf(argv[0], "0x%x", &io) != 1 ||
+X sscanf(argv[1], "%d", &irq) != 1)
+X usage();
+X
+X return msnd_write_cfg_logical(config_port, 1, io, 0, irq, 0);
+}
+X
+static int cfg_ide(int argc, char *argv[])
+{
+X int io0, io1, irq;
+X
+X if (argc < 3 ||
+X sscanf(argv[0], "0x%x", &io0) != 1 ||
+X sscanf(argv[0], "0x%x", &io1) != 1 ||
+X sscanf(argv[1], "%d", &irq) != 1)
+X usage();
+X
+X return msnd_write_cfg_logical(config_port, 2, io0, io1, irq, 0);
+}
+X
+static int cfg_joystick(int argc, char *argv[])
+{
+X int io;
+X
+X if (argc < 1 ||
+X sscanf(argv[0], "0x%x", &io) != 1)
+X usage();
+X
+X return msnd_write_cfg_logical(config_port, 3, io, 0, 0, 0);
+}
+X
+int main(int argc, char *argv[])
+{
+X char *device;
+X int rv = 0;
+X
+X --argc; ++argv;
+X
+X if (argc < 2)
+X usage();
+X
+X sscanf(argv[0], "0x%x", &config_port);
+X if (config_port != 0x250 && config_port != 0x260 && config_port != 0x270) {
+X fprintf(stderr, "error: <config port> must be 0x250, 0x260 or 0x270\n");
+X exit(1);
+X }
+X if (ioperm(config_port, 2, 1)) {
+X perror("ioperm");
+X fprintf(stderr, "note: pinnaclecfg must be run as root\n");
+X exit(1);
+X }
+X device = argv[1];
+X
+X argc -= 2; argv += 2;
+X
+X if (strcmp(device, "reset") == 0)
+X rv = cfg_reset();
+X else if (strcmp(device, "show") == 0)
+X rv = cfg_show();
+X else if (strcmp(device, "dsp") == 0)
+X rv = cfg_dsp(argc, argv);
+X else if (strcmp(device, "mpu") == 0)
+X rv = cfg_mpu(argc, argv);
+X else if (strcmp(device, "ide") == 0)
+X rv = cfg_ide(argc, argv);
+X else if (strcmp(device, "joystick") == 0)
+X rv = cfg_joystick(argc, argv);
+X else {
+X fprintf(stderr, "error: unknown device %s\n", device);
+X usage();
+X }
+X
+X if (rv)
+X fprintf(stderr, "error: device configuration failed\n");
+X
+X return 0;
+}
+SHAR_EOF
+ $shar_touch -am 1204092598 'MultiSound.d/pinnaclecfg.c' &&
+ chmod 0664 'MultiSound.d/pinnaclecfg.c' ||
+ $echo 'restore of' 'MultiSound.d/pinnaclecfg.c' 'failed'
+ if ( md5sum --help 2>&1 | grep 'sage: md5sum \[' ) >/dev/null 2>&1 \
+ && ( md5sum --version 2>&1 | grep -v 'textutils 1.12' ) >/dev/null; then
+ md5sum -c << SHAR_EOF >/dev/null 2>&1 \
+ || $echo 'MultiSound.d/pinnaclecfg.c:' 'MD5 check failed'
+366bdf27f0db767a3c7921d0a6db20fe MultiSound.d/pinnaclecfg.c
+SHAR_EOF
+ else
+ shar_count="`LC_ALL= LC_CTYPE= LANG= wc -c < 'MultiSound.d/pinnaclecfg.c'`"
+ test 10235 -eq "$shar_count" ||
+ $echo 'MultiSound.d/pinnaclecfg.c:' 'original size' '10235,' 'current size' "$shar_count!"
+ fi
+fi
+# ============= MultiSound.d/Makefile ==============
+if test -f 'MultiSound.d/Makefile' && test "$first_param" != -c; then
+ $echo 'x -' SKIPPING 'MultiSound.d/Makefile' '(file already exists)'
+else
+ $echo 'x -' extracting 'MultiSound.d/Makefile' '(text)'
+ sed 's/^X//' << 'SHAR_EOF' > 'MultiSound.d/Makefile' &&
+CC = gcc
+CFLAGS = -O
+PROGS = setdigital msndreset pinnaclecfg conv
+X
+all: $(PROGS)
+X
+clean:
+X rm -f $(PROGS)
+SHAR_EOF
+ $shar_touch -am 1204092398 'MultiSound.d/Makefile' &&
+ chmod 0664 'MultiSound.d/Makefile' ||
+ $echo 'restore of' 'MultiSound.d/Makefile' 'failed'
+ if ( md5sum --help 2>&1 | grep 'sage: md5sum \[' ) >/dev/null 2>&1 \
+ && ( md5sum --version 2>&1 | grep -v 'textutils 1.12' ) >/dev/null; then
+ md5sum -c << SHAR_EOF >/dev/null 2>&1 \
+ || $echo 'MultiSound.d/Makefile:' 'MD5 check failed'
+76ca8bb44e3882edcf79c97df6c81845 MultiSound.d/Makefile
+SHAR_EOF
+ else
+ shar_count="`LC_ALL= LC_CTYPE= LANG= wc -c < 'MultiSound.d/Makefile'`"
+ test 106 -eq "$shar_count" ||
+ $echo 'MultiSound.d/Makefile:' 'original size' '106,' 'current size' "$shar_count!"
+ fi
+fi
+# ============= MultiSound.d/conv.l ==============
+if test -f 'MultiSound.d/conv.l' && test "$first_param" != -c; then
+ $echo 'x -' SKIPPING 'MultiSound.d/conv.l' '(file already exists)'
+else
+ $echo 'x -' extracting 'MultiSound.d/conv.l' '(text)'
+ sed 's/^X//' << 'SHAR_EOF' > 'MultiSound.d/conv.l' &&
+%%
+[ \n\t,\r]
+\;.*
+DB
+[0-9A-Fa-f]+H { int n; sscanf(yytext, "%xH", &n); printf("%c", n); }
+%%
+int yywrap() { return 1; }
+main() { yylex(); }
+SHAR_EOF
+ $shar_touch -am 0828231798 'MultiSound.d/conv.l' &&
+ chmod 0664 'MultiSound.d/conv.l' ||
+ $echo 'restore of' 'MultiSound.d/conv.l' 'failed'
+ if ( md5sum --help 2>&1 | grep 'sage: md5sum \[' ) >/dev/null 2>&1 \
+ && ( md5sum --version 2>&1 | grep -v 'textutils 1.12' ) >/dev/null; then
+ md5sum -c << SHAR_EOF >/dev/null 2>&1 \
+ || $echo 'MultiSound.d/conv.l:' 'MD5 check failed'
+d2411fc32cd71a00dcdc1f009e858dd2 MultiSound.d/conv.l
+SHAR_EOF
+ else
+ shar_count="`LC_ALL= LC_CTYPE= LANG= wc -c < 'MultiSound.d/conv.l'`"
+ test 141 -eq "$shar_count" ||
+ $echo 'MultiSound.d/conv.l:' 'original size' '141,' 'current size' "$shar_count!"
+ fi
+fi
+# ============= MultiSound.d/msndreset.c ==============
+if test -f 'MultiSound.d/msndreset.c' && test "$first_param" != -c; then
+ $echo 'x -' SKIPPING 'MultiSound.d/msndreset.c' '(file already exists)'
+else
+ $echo 'x -' extracting 'MultiSound.d/msndreset.c' '(text)'
+ sed 's/^X//' << 'SHAR_EOF' > 'MultiSound.d/msndreset.c' &&
+/*********************************************************************
+X *
+X * msndreset.c - resets the MultiSound card
+X *
+X * Copyright (C) 1998 Andrew Veliath
+X *
+X * This program is free software; you can redistribute it and/or modify
+X * it under the terms of the GNU General Public License as published by
+X * the Free Software Foundation; either version 2 of the License, or
+X * (at your option) any later version.
+X *
+X * This program is distributed in the hope that it will be useful,
+X * but WITHOUT ANY WARRANTY; without even the implied warranty of
+X * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+X * GNU General Public License for more details.
+X *
+X * You should have received a copy of the GNU General Public License
+X * along with this program; if not, write to the Free Software
+X * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+X *
+X ********************************************************************/
+X
+#include <stdio.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <sys/ioctl.h>
+#include <sys/soundcard.h>
+X
+int main(int argc, char *argv[])
+{
+X int fd;
+X
+X if (argc != 2) {
+X fprintf(stderr, "usage: msndreset <mixer device>\n");
+X exit(1);
+X }
+X
+X if ((fd = open(argv[1], O_RDWR)) < 0) {
+X perror(argv[1]);
+X exit(1);
+X }
+X
+X if (ioctl(fd, SOUND_MIXER_PRIVATE1, 0) < 0) {
+X fprintf(stderr, "error: msnd ioctl reset failed\n");
+X perror("ioctl");
+X close(fd);
+X exit(1);
+X }
+X
+X close(fd);
+X
+X return 0;
+}
+SHAR_EOF
+ $shar_touch -am 1204100698 'MultiSound.d/msndreset.c' &&
+ chmod 0664 'MultiSound.d/msndreset.c' ||
+ $echo 'restore of' 'MultiSound.d/msndreset.c' 'failed'
+ if ( md5sum --help 2>&1 | grep 'sage: md5sum \[' ) >/dev/null 2>&1 \
+ && ( md5sum --version 2>&1 | grep -v 'textutils 1.12' ) >/dev/null; then
+ md5sum -c << SHAR_EOF >/dev/null 2>&1 \
+ || $echo 'MultiSound.d/msndreset.c:' 'MD5 check failed'
+c52f876521084e8eb25e12e01dcccb8a MultiSound.d/msndreset.c
+SHAR_EOF
+ else
+ shar_count="`LC_ALL= LC_CTYPE= LANG= wc -c < 'MultiSound.d/msndreset.c'`"
+ test 1472 -eq "$shar_count" ||
+ $echo 'MultiSound.d/msndreset.c:' 'original size' '1472,' 'current size' "$shar_count!"
+ fi
+fi
+rm -fr _sh01426
+exit 0
diff --git a/Documentation/sound/oss/OPL3 b/Documentation/sound/oss/OPL3
new file mode 100644
index 0000000..2468ff8
--- /dev/null
+++ b/Documentation/sound/oss/OPL3
@@ -0,0 +1,6 @@
+A pure OPL3 card is nice and easy to configure. Simply do
+
+insmod opl3 io=0x388
+
+Change the I/O address in the very unlikely case this card is differently
+configured
diff --git a/Documentation/sound/oss/Opti b/Documentation/sound/oss/Opti
new file mode 100644
index 0000000..c15af3c
--- /dev/null
+++ b/Documentation/sound/oss/Opti
@@ -0,0 +1,222 @@
+Support for the OPTi 82C931 chip
+--------------------------------
+Note: parts of this README file apply also to other
+cards that use the mad16 driver.
+
+Some items in this README file are based on features
+added to the sound driver after Linux-2.1.91 was out.
+By the time of writing this I do not know which official
+kernel release will include these features.
+Please do not report inconsistencies on older Linux
+kernels.
+
+The OPTi 82C931 is supported in its non-PnP mode.
+Usually you do not need to set jumpers, etc. The sound driver
+will check the card status and if it is required it will
+force the card into a mode in which it can be programmed.
+
+If you have another OS installed on your computer it is recommended
+that Linux and the other OS use the same resources.
+
+Also, it is recommended that resources specified in /etc/modprobe.conf
+and resources specified in /etc/isapnp.conf agree.
+
+Compiling the sound driver
+--------------------------
+I highly recommend that you build a modularized sound driver.
+This document does not cover a sound-driver which is built in
+the kernel.
+
+Sound card support should be enabled as a module (chose m).
+Answer 'm' for these items:
+ Generic OPL2/OPL3 FM synthesizer support (CONFIG_SOUND_ADLIB)
+ Microsoft Sound System support (CONFIG_SOUND_MSS)
+ Support for OPTi MAD16 and/or Mozart based cards (CONFIG_SOUND_MAD16)
+ FM synthesizer (YM3812/OPL-3) support (CONFIG_SOUND_YM3812)
+
+The configuration menu may ask for addresses, IRQ lines or DMA
+channels. If the card is used as a module the module loading
+options will override these values.
+
+For the OPTi 931 you can answer 'n' to:
+ Support MIDI in older MAD16 based cards (requires SB) (CONFIG_SOUND_MAD16_OLDCARD)
+If you do need MIDI support in a Mozart or C928 based card you
+need to answer 'm' to the above question. In that case you will
+also need to answer 'm' to:
+ '100% Sound Blaster compatibles (SB16/32/64, ESS, Jazz16) support' (CONFIG_SOUND_SB)
+
+Go on and compile your kernel and modules. Install the modules. Run depmod -a.
+
+Using isapnptools
+-----------------
+In most systems with a PnP BIOS you do not need to use isapnp. The
+initialization provided by the BIOS is sufficient for the driver
+to pick up the card and continue initialization.
+
+If that fails, or if you have other PnP cards, you need to use isapnp
+to initialize the card.
+This was tested with isapnptools-1.11 but I recommend that you use
+isapnptools-1.13 (or newer). Run pnpdump to dump the information
+about your PnP cards. Then edit the resulting file and select
+the options of your choice. This file is normally installed as
+/etc/isapnp.conf.
+
+The driver has one limitation with respect to I/O port resources:
+IO3 base must be 0x0E0C. Although isapnp allows other ports, this
+address is hard-coded into the driver.
+
+Using kmod and autoloading the sound driver
+-------------------------------------------
+Comment: as of linux-2.1.90 kmod is replacing kerneld.
+The config file '/etc/modprobe.conf' is used as before.
+
+This is the sound part of my /etc/modprobe.conf file.
+Following that I will explain each line.
+
+alias mixer0 mad16
+alias audio0 mad16
+alias midi0 mad16
+alias synth0 opl3
+options sb mad16=1
+options mad16 irq=10 dma=0 dma16=1 io=0x530 joystick=1 cdtype=0
+options opl3 io=0x388
+install mad16 /sbin/modprobe -i mad16 && /sbin/ad1848_mixer_reroute 14 8 15 3 16 6
+
+If you have an MPU daughtercard or onboard MPU you will want to add to the
+"options mad16" line - eg
+
+options mad16 irq=5 dma=0 dma16=3 io=0x530 mpu_io=0x330 mpu_irq=9
+
+To set the I/O and IRQ of the MPU.
+
+
+Explain:
+
+alias mixer0 mad16
+alias audio0 mad16
+alias midi0 mad16
+alias synth0 opl3
+
+When any sound device is opened the kernel requests auto-loading
+of char-major-14. There is a built-in alias that translates this
+request to loading the main sound module.
+
+The sound module in its turn will request loading of a sub-driver
+for mixer, audio, midi or synthesizer device. The first 3 are
+supported by the mad16 driver. The synth device is supported
+by the opl3 driver.
+
+There is currently no way to autoload the sound device driver
+if more than one card is installed.
+
+options sb mad16=1
+
+This is left for historical reasons. If you enable the
+config option 'Support MIDI in older MAD16 based cards (requires SB)'
+or if you use an older mad16 driver it will force loading of the
+SoundBlaster driver. This option tells the SB driver not to look
+for a SB card but to wait for the mad16 driver.
+
+options mad16 irq=10 dma=0 dma16=1 io=0x530 joystick=1 cdtype=0
+options opl3 io=0x388
+
+post-install mad16 /sbin/ad1848_mixer_reroute 14 8 15 3 16 6
+
+This sets resources and options for the mad16 and opl3 drivers.
+I use two DMA channels (only one is required) to enable full duplex.
+joystick=1 enables the joystick port. cdtype=0 disables the cd port.
+You can also set mpu_io and mpu_irq in the mad16 options for the
+uart401 driver.
+
+This tells modprobe to run /sbin/ad1848_mixer_reroute after
+mad16 is successfully loaded and initialized. The source
+for ad1848_mixer_reroute is appended to the end of this readme
+file. It is impossible for the sound driver to know the actual
+connections to the mixer. The 3 inputs intended for cd, synth
+and line-in are mapped to the generic inputs line1, line2 and
+line3. This program reroutes these mixer channels to their
+right names (note the right mapping depends on the actual sound
+card that you use).
+The numeric parameters mean:
+ 14=line1 8=cd - reroute line1 to the CD input.
+ 15=line2 3=synth - reroute line2 to the synthesizer input.
+ 16=line3 6=line - reroute line3 to the line input.
+For reference on other input names look at the file
+/usr/include/linux/soundcard.h.
+
+Using a joystick
+-----------------
+You must enable a joystick in the mad16 options. (also
+in /etc/isapnp.conf if you use it).
+Tested with regular analog joysticks.
+
+A CDROM drive connected to the sound card
+-----------------------------------------
+The 82C931 chip has support only for secondary ATAPI cdrom.
+(cdtype=8). Loading the mad16 driver resets the C931 chip
+and if a cdrom was already mounted it may cause a complete
+system hang. Do not use the sound card if you have an alternative.
+If you do use the sound card it is important that you load
+the mad16 driver (use "modprobe mad16" to prevent auto-unloading)
+before the cdrom is accessed the first time.
+
+Using the sound driver built-in to the kernel may help here, but...
+Most new systems have a PnP BIOS and also two IDE controllers.
+The IDE controller on the sound card may be needed only on older
+systems (which have only one IDE controller) but these systems
+also do not have a PnP BIOS - requiring isapnptools and a modularized
+driver.
+
+Known problems
+--------------
+1. See the section on "A CDROM drive connected to the sound card".
+
+2. On my system the codec cannot capture companded sound samples.
+ (eg., recording from /dev/audio). When any companded capture is
+ requested I get stereo-16 bit samples instead. Playback of
+ companded samples works well. Apparently this problem is not common
+ to all C931 based cards. I do not know how to identify cards that
+ have this problem.
+
+Source for ad1848_mixer_reroute.c
+---------------------------------
+#include <stdio.h>
+#include <fcntl.h>
+#include <linux/soundcard.h>
+
+static char *mixer_names[SOUND_MIXER_NRDEVICES] =
+ SOUND_DEVICE_LABELS;
+
+int
+main(int argc, char **argv) {
+ int val, from, to;
+ int i, fd;
+
+ fd = open("/dev/mixer", O_RDWR);
+ if(fd < 0) {
+ perror("/dev/mixer");
+ return 1;
+ }
+
+ for(i = 2; i < argc; i += 2) {
+ from = atoi(argv[i-1]);
+ to = atoi(argv[i]);
+
+ if(to == SOUND_MIXER_NONE)
+ fprintf(stderr, "%s: turning off mixer %s\n",
+ argv[0], mixer_names[to]);
+ else
+ fprintf(stderr, "%s: rerouting mixer %s to %s\n",
+ argv[0], mixer_names[from], mixer_names[to]);
+
+ val = from << 8 | to;
+
+ if(ioctl(fd, SOUND_MIXER_PRIVATE2, &val)) {
+ perror("AD1848 mixer reroute");
+ return 1;
+ }
+ }
+
+ return 0;
+}
+
diff --git a/Documentation/sound/oss/PAS16 b/Documentation/sound/oss/PAS16
new file mode 100644
index 0000000..951b3dc
--- /dev/null
+++ b/Documentation/sound/oss/PAS16
@@ -0,0 +1,163 @@
+Pro Audio Spectrum 16 for 2.3.99 and later
+=========================================
+by Thomas Molina (tmolina@home.com)
+last modified 3 Mar 2001
+Acknowledgement to Axel Boldt (boldt@math.ucsb.edu) for stuff taken
+from Configure.help, Riccardo Facchetti for stuff from README.OSS,
+and others whose names I could not find.
+
+This documentation is relevant for the PAS16 driver (pas2_card.c and
+friends) under kernel version 2.3.99 and later. If you are
+unfamiliar with configuring sound under Linux, please read the
+Sound-HOWTO, Documentation/sound/oss/Introduction and other
+relevant docs first.
+
+The following information is relevant information from README.OSS
+and legacy docs for the Pro Audio Spectrum 16 (PAS16):
+==================================================================
+
+The pas2_card.c driver supports the following cards --
+Pro Audio Spectrum 16 (PAS16) and compatibles:
+ Pro Audio Spectrum 16
+ Pro Audio Studio 16
+ Logitech Sound Man 16
+ NOTE! The original Pro Audio Spectrum as well as the PAS+ are not
+ and will not be supported by the driver.
+
+The sound driver configuration dialog
+-------------------------------------
+
+Sound configuration starts by making some yes/no questions. Be careful
+when answering to these questions since answering y to a question may
+prevent some later ones from being asked. For example don't answer y to
+the question about (PAS16) if you don't really have a PAS16. Sound
+configuration may also be made modular by answering m to configuration
+options presented.
+
+Note also that all questions may not be asked. The configuration program
+may disable some questions depending on the earlier choices. It may also
+select some options automatically as well.
+
+ "ProAudioSpectrum 16 support",
+ - Answer 'y'_ONLY_ if you have a Pro Audio Spectrum _16_,
+ Pro Audio Studio 16 or Logitech SoundMan 16 (be sure that
+ you read the above list correctly). Don't answer 'y' if you
+ have some other card made by Media Vision or Logitech since they
+ are not PAS16 compatible.
+ NOTE! Since 3.5-beta10 you need to enable SB support (next question)
+ if you want to use the SB emulation of PAS16. It's also possible to
+ the emulation if you want to use a true SB card together with PAS16
+ (there is another question about this that is asked later).
+
+ "Generic OPL2/OPL3 FM synthesizer support",
+ - Answer 'y' if your card has a FM chip made by Yamaha (OPL2/OPL3/OPL4).
+ The PAS16 has an OPL3-compatible FM chip.
+
+With PAS16 you can use two audio device files at the same time. /dev/dsp (and
+/dev/audio) is connected to the 8/16 bit native codec and the /dev/dsp1 (and
+/dev/audio1) is connected to the SB emulation (8 bit mono only).
+
+
+The new stuff for 2.3.99 and later
+============================================================================
+The following configuration options from Documentation/Configure.help
+are relevant to configuring the PAS16:
+
+Sound card support
+CONFIG_SOUND
+ If you have a sound card in your computer, i.e. if it can say more
+ than an occasional beep, say Y. Be sure to have all the information
+ about your sound card and its configuration down (I/O port,
+ interrupt and DMA channel), because you will be asked for it.
+
+ You want to read the Sound-HOWTO, available from
+ http://www.tldp.org/docs.html#howto . General information
+ about the modular sound system is contained in the files
+ Documentation/sound/oss/Introduction. The file
+ Documentation/sound/oss/README.OSS contains some slightly outdated but
+ still useful information as well.
+
+OSS sound modules
+CONFIG_SOUND_OSS
+ OSS is the Open Sound System suite of sound card drivers. They make
+ sound programming easier since they provide a common API. Say Y or M
+ here (the module will be called sound.o) if you haven't found a
+ driver for your sound card above, then pick your driver from the
+ list below.
+
+Persistent DMA buffers
+CONFIG_SOUND_DMAP
+ Linux can often have problems allocating DMA buffers for ISA sound
+ cards on machines with more than 16MB of RAM. This is because ISA
+ DMA buffers must exist below the 16MB boundary and it is quite
+ possible that a large enough free block in this region cannot be
+ found after the machine has been running for a while. If you say Y
+ here the DMA buffers (64Kb) will be allocated at boot time and kept
+ until the shutdown. This option is only useful if you said Y to
+ "OSS sound modules", above. If you said M to "OSS sound modules"
+ then you can get the persistent DMA buffer functionality by passing
+ the command-line argument "dmabuf=1" to the sound.o module.
+
+ Say y here for PAS16.
+
+ProAudioSpectrum 16 support
+CONFIG_SOUND_PAS
+ Answer Y only if you have a Pro Audio Spectrum 16, ProAudio Studio
+ 16 or Logitech SoundMan 16 sound card. Don't answer Y if you have
+ some other card made by Media Vision or Logitech since they are not
+ PAS16 compatible. It is not necessary to enable the separate
+ Sound Blaster support; it is included in the PAS driver.
+
+ If you compile the driver into the kernel, you have to add
+ "pas2=<io>,<irq>,<dma>,<dma2>,<sbio>,<sbirq>,<sbdma>,<sbdma2>
+ to the kernel command line.
+
+FM Synthesizer (YM3812/OPL-3) support
+CONFIG_SOUND_YM3812
+ Answer Y if your card has a FM chip made by Yamaha (OPL2/OPL3/OPL4).
+ Answering Y is usually a safe and recommended choice, however some
+ cards may have software (TSR) FM emulation. Enabling FM support with
+ these cards may cause trouble (I don't currently know of any such
+ cards, however).
+ Please read the file Documentation/sound/oss/OPL3 if your card has an
+ OPL3 chip.
+ If you compile the driver into the kernel, you have to add
+ "opl3=<io>" to the kernel command line.
+
+ If you compile your drivers into the kernel, you MUST configure
+ OPL3 support as a module for PAS16 support to work properly.
+ You can then get OPL3 functionality by issuing the command:
+ insmod opl3
+ In addition, you must either add the following line to
+ /etc/modprobe.conf:
+ options opl3 io=0x388
+ or else add the following line to /etc/lilo.conf:
+ opl3=0x388
+
+
+EXAMPLES
+===================================================================
+To use the PAS16 in my computer I have enabled the following sound
+configuration options:
+
+CONFIG_SOUND=y
+CONFIG_SOUND_OSS=y
+CONFIG_SOUND_TRACEINIT=y
+CONFIG_SOUND_DMAP=y
+CONFIG_SOUND_PAS=y
+CONFIG_SOUND_SB=n
+CONFIG_SOUND_YM3812=m
+
+I have also included the following append line in /etc/lilo.conf:
+append="pas2=0x388,10,3,-1,0x220,5,1,-1 sb=0x220,5,1,-1 opl3=0x388"
+
+The io address of 0x388 is default configuration on the PAS16. The
+irq of 10 and dma of 3 may not match your installation. The above
+configuration enables PAS16, 8-bit Soundblaster and OPL3
+functionality. If Soundblaster functionality is not desired, the
+following line would be appropriate:
+append="pas2=0x388,10,3,-1,0,-1,-1,-1 opl3=0x388"
+
+If sound is built totally modular, the above options may be
+specified in /etc/modprobe.conf for pas2, sb and opl3
+respectively.
diff --git a/Documentation/sound/oss/PSS b/Documentation/sound/oss/PSS
new file mode 100644
index 0000000..187b952
--- /dev/null
+++ b/Documentation/sound/oss/PSS
@@ -0,0 +1,41 @@
+The PSS cards and other ECHO based cards provide an onboard DSP with
+downloadable programs and also has an AD1848 "Microsoft Sound System"
+device. The PSS driver enables MSS and MPU401 modes of the card. SB
+is not enabled since it doesn't work concurrently with MSS.
+
+If you build this driver as a module then the driver takes the following
+parameters
+
+pss_io. The I/O base the PSS card is configured at (normally 0x220
+ or 0x240)
+
+mss_io The base address of the Microsoft Sound System interface.
+ This is normally 0x530, but may be 0x604 or other addresses.
+
+mss_irq The interrupt assigned to the Microsoft Sound System
+ emulation. IRQ's 3,5,7,9,10,11 and 12 are available. If you
+ get IRQ errors be sure to check the interrupt is set to
+ "ISA/Legacy" in the BIOS on modern machines.
+
+mss_dma The DMA channel used by the Microsoft Sound System.
+ This can be 0, 1, or 3. DMA 0 is not available on older
+ machines and will cause a crash on them.
+
+mpu_io The MPU emulation base address. This sets the base of the
+ synthesizer. It is typically 0x330 but can be altered.
+
+mpu_irq The interrupt to use for the synthesizer. It must differ
+ from the IRQ used by the Microsoft Sound System port.
+
+
+The mpu_io/mpu_irq fields are optional. If they are not specified the
+synthesizer parts are not configured.
+
+When the module is loaded it looks for a file called
+/etc/sound/pss_synth. This is the firmware file from the DOS install disks.
+This fil holds a general MIDI emulation. The file expected is called
+genmidi.ld on newer DOS driver install disks and synth.ld on older ones.
+
+You can also load alternative DSP algorithms into the card if you wish. One
+alternative driver can be found at http://www.mpg123.de/
+
diff --git a/Documentation/sound/oss/PSS-updates b/Documentation/sound/oss/PSS-updates
new file mode 100644
index 0000000..c84dd75
--- /dev/null
+++ b/Documentation/sound/oss/PSS-updates
@@ -0,0 +1,88 @@
+ This file contains notes for users of PSS sound cards who wish to use the
+newly added features of the newest version of this driver.
+
+ The major enhancements present in this new revision of this driver is the
+addition of two new module parameters that allow you to take full advantage of
+all the features present on your PSS sound card. These features include the
+ability to enable both the builtin CDROM and joystick ports.
+
+pss_enable_joystick
+
+ This parameter is basically a flag. A 0 will leave the joystick port
+disabled, while a non-zero value would enable the joystick port. The default
+setting is pss_enable_joystick=0 as this keeps this driver fully compatible
+with systems that were using previous versions of this driver. If you wish to
+enable the joystick port you will have to add pss_enable_joystick=1 as an
+argument to the driver. To actually use the joystick port you will then have
+to load the joystick driver itself. Just remember to load the joystick driver
+AFTER the pss sound driver.
+
+pss_cdrom_port
+
+ This parameter takes a port address as its parameter. Any available port
+address can be specified to enable the CDROM port, except for 0x0 and -1 as
+these values would leave the port disabled. Like the joystick port, the cdrom
+port will require that an appropriate CDROM driver be loaded before you can make
+use of the newly enabled CDROM port. Like the joystick port option above,
+remember to load the CDROM driver AFTER the pss sound driver. While it may
+differ on some PSS sound cards, all the PSS sound cards that I have seen have a
+builtin Wearnes CDROM port. If this is the case with your PSS sound card you
+should load aztcd with the appropriate port option that matches the port you
+assigned to the CDROM port when you loaded your pss sound driver. (ex.
+modprobe pss pss_cdrom_port=0x340 && modprobe aztcd aztcd=0x340) The default
+setting of this parameter leaves the CDROM port disabled to maintain full
+compatibility with systems using previous versions of this driver.
+
+ Other options have also been added for the added convenience and utility
+of the user. These options are only available if this driver is loaded as a
+module.
+
+pss_no_sound
+
+ This module parameter is a flag that can be used to tell the driver to
+just configure non-sound components. 0 configures all components, a non-0
+value will only attept to configure the CDROM and joystick ports. This
+parameter can be used by a user who only wished to use the builtin joystick
+and/or CDROM port(s) of his PSS sound card. If this driver is loaded with this
+parameter and with the parameter below set to true then a user can safely unload
+this driver with the following command "rmmod pss && rmmod ad1848 && rmmod
+mpu401 && rmmod sound && rmmod soundcore" and retain the full functionality of
+his CDROM and/or joystick port(s) while gaining back the memory previously used
+by the sound drivers. This default setting of this parameter is 0 to retain
+full behavioral compatibility with previous versions of this driver.
+
+pss_keep_settings
+
+ This parameter can be used to specify whether you want the driver to reset
+all emulations whenever its unloaded. This can be useful for those who are
+sharing resources (io ports, IRQ's, DMA's) between different ISA cards. This
+flag can also be useful in that future versions of this driver may reset all
+emulations by default on the driver's unloading (as it probably should), so
+specifying it now will ensure that all future versions of this driver will
+continue to work as expected. The default value of this parameter is 1 to
+retain full behavioral compatibility with previous versions of this driver.
+
+pss_firmware
+
+ This parameter can be used to specify the file containing the firmware
+code so that a user could tell the driver where that file is located instead
+of having to put it in a predefined location with a predefined name. The
+default setting of this parameter is "/etc/sound/pss_synth" as this was the
+path and filename the hardcoded value in the previous versions of this driver.
+
+Examples:
+
+# Normal PSS sound card system, loading of drivers.
+# Should be specified in an rc file (ex. Slackware uses /etc/rc.d/rc.modules).
+
+/sbin/modprobe pss pss_io=0x220 mpu_io=0x338 mpu_irq=9 mss_io=0x530 mss_irq=10 mss_dma=1 pss_cdrom_port=0x340 pss_enable_joystick=1
+/sbin/modprobe aztcd aztcd=0x340
+/sbin/modprobe joystick
+
+# System using the PSS sound card just for its CDROM and joystick ports.
+# Should be specified in an rc file (ex. Slackware uses /etc/rc.d/rc.modules).
+
+/sbin/modprobe pss pss_io=0x220 pss_cdrom_port=0x340 pss_enable_joystick=1 pss_no_sound=1
+/sbin/rmmod pss && /sbin/rmmod ad1848 && /sbin/rmmod mpu401 && /sbin/rmmod sound && /sbin/rmmod soundcore # This line not needed, but saves memory.
+/sbin/modprobe aztcd aztcd=0x340
+/sbin/modprobe joystick
diff --git a/Documentation/sound/oss/README.OSS b/Documentation/sound/oss/README.OSS
new file mode 100644
index 0000000..fd42b05
--- /dev/null
+++ b/Documentation/sound/oss/README.OSS
@@ -0,0 +1,1456 @@
+Introduction
+------------
+
+This file is a collection of all the old Readme files distributed with
+OSS/Lite by Hannu Savolainen. Since the new Linux sound driver is founded
+on it I think these information may still be interesting for users that
+have to configure their sound system.
+
+Be warned: Alan Cox is the current maintainer of the Linux sound driver so if
+you have problems with it, please contact him or the current device-specific
+driver maintainer (e.g. for aedsp16 specific problems contact me). If you have
+patches, contributions or suggestions send them to Alan: I'm sure they are
+welcome.
+
+In this document you will find a lot of references about OSS/Lite or ossfree:
+they are gone forever. Keeping this in mind and with a grain of salt this
+document can be still interesting and very helpful.
+
+[ File edited 17.01.1999 - Riccardo Facchetti ]
+[ Edited miroSOUND section 19.04.2001 - Robert Siemer ]
+
+OSS/Free version 3.8 release notes
+----------------------------------
+
+Please read the SOUND-HOWTO (available from sunsite.unc.edu and other Linux FTP
+sites). It gives instructions about using sound with Linux. It's bit out of
+date but still very useful. Information about bug fixes and such things
+is available from the web page (see above).
+
+Please check http://www.opensound.com/pguide for more info about programming
+with OSS API.
+
+ ====================================================
+- THIS VERSION ____REQUIRES____ Linux 2.1.57 OR LATER.
+ ====================================================
+
+Packages "snd-util-3.8.tar.gz" and "snd-data-0.1.tar.Z"
+contain useful utilities to be used with this driver.
+See http://www.opensound.com/ossfree/getting.html for
+download instructions.
+
+If you are looking for the installation instructions, please
+look forward into this document.
+
+Supported sound cards
+---------------------
+
+See below.
+
+Contributors
+------------
+
+This driver contains code by several contributors. In addition several other
+persons have given useful suggestions. The following is a list of major
+contributors. (I could have forgotten some names.)
+
+ Craig Metz 1/2 of the PAS16 Mixer and PCM support
+ Rob Hooft Volume computation algorithm for the FM synth.
+ Mika Liljeberg uLaw encoding and decoding routines
+ Jeff Tranter Linux SOUND HOWTO document
+ Greg Lee Volume computation algorithm for the GUS and
+ lots of valuable suggestions.
+ Andy Warner ISC port
+ Jim Lowe,
+ Amancio Hasty Jr FreeBSD/NetBSD port
+ Anders Baekgaard Bug hunting and valuable suggestions.
+ Joerg Schubert SB16 DSP support (initial version).
+ Andrew Robinson Improvements to the GUS driver
+ Megens SA MIDI recording for SB and SB Pro (initial version).
+ Mikael Nordqvist Linear volume support for GUS and
+ nonblocking /dev/sequencer.
+ Ian Hartas SVR4.2 port
+ Markus Aroharju and
+ Risto Kankkunen Major contributions to the mixer support
+ of GUS v3.7.
+ Hunyue Yau Mixer support for SG NX Pro.
+ Marc Hoffman PSS support (initial version).
+ Rainer Vranken Initialization for Jazz16 (initial version).
+ Peter Trattler Initial version of loadable module support for Linux.
+ JRA Gibson 16 bit mode for Jazz16 (initial version)
+ Davor Jadrijevic MAD16 support (initial version)
+ Gregor Hoffleit Mozart support (initial version)
+ Riccardo Facchetti Audio Excel DSP 16 (aedsp16) support
+ James Hightower Spotting a tiny but important bug in CS423x support.
+ Denis Sablic OPTi 82C924 specific enhancements (non PnP mode)
+ Tim MacKenzie Full duplex support for OPTi 82C930.
+
+ Please look at lowlevel/README for more contributors.
+
+There are probably many other names missing. If you have sent me some
+patches and your name is not in the above list, please inform me.
+
+Sending your contributions or patches
+-------------------------------------
+
+First of all it's highly recommended to contact me before sending anything
+or before even starting to do any work. Tell me what you suggest to be
+changed or what you have planned to do. Also ensure you are using the
+very latest (development) version of OSS/Free since the change may already be
+implemented there. In general it's a major waste of time to try to improve a
+several months old version. Information about the latest version can be found
+from http://www.opensound.com/ossfree. In general there is no point in
+sending me patches relative to production kernels.
+
+Sponsors etc.
+-------------
+
+The following companies have greatly helped development of this driver
+in form of a free copy of their product:
+
+Novell, Inc. UnixWare personal edition + SDK
+The Santa Cruz Operation, Inc. A SCO OpenServer + SDK
+Ensoniq Corp, a SoundScape card and extensive amount of assistance
+MediaTrix Peripherals Inc, a AudioTrix Pro card + SDK
+Acer, Inc. a pair of AcerMagic S23 cards.
+
+In addition the following companies have provided me sufficient amount
+of technical information at least some of their products (free or $$$):
+
+Advanced Gravis Computer Technology Ltd.
+Media Vision Inc.
+Analog Devices Inc.
+Logitech Inc.
+Aztech Labs Inc.
+Crystal Semiconductor Corporation,
+Integrated Circuit Systems Inc.
+OAK Technology
+OPTi
+Turtle Beach
+miro
+Ad Lib Inc. ($$)
+Music Quest Inc. ($$)
+Creative Labs ($$$)
+
+If you have some problems
+=========================
+
+Read the sound HOWTO (sunsite.unc.edu:/pub/Linux/docs/...?).
+Also look at the home page (http://www.opensound.com/ossfree). It may
+contain info about some recent bug fixes.
+
+It's likely that you have some problems when trying to use the sound driver
+first time. Sound cards don't have standard configuration so there are no
+good default configuration to use. Please try to use same I/O, DMA and IRQ
+values for the sound card than with DOS.
+
+If you get an error message when trying to use the driver, please look
+at /var/adm/messages for more verbose error message.
+
+
+The following errors are likely with /dev/dsp and /dev/audio.
+
+ - "No such device or address".
+ This error indicates that there are no suitable hardware for the
+ device file or the sound driver has been compiled without support for
+ this particular device. For example /dev/audio and /dev/dsp will not
+ work if "digitized voice support" was not enabled during "make config".
+
+ - "Device or resource busy". Probably the IRQ (or DMA) channel
+ required by the sound card is in use by some other device/driver.
+
+ - "I/O error". Almost certainly (99%) it's an IRQ or DMA conflict.
+ Look at the kernel messages in /var/adm/notice for more info.
+
+ - "Invalid argument". The application is calling ioctl()
+ with impossible parameters. Check that the application is
+ for sound driver version 2.X or later.
+
+Linux installation
+==================
+
+IMPORTANT! Read this if you are installing a separately
+ distributed version of this driver.
+
+ Check that your kernel version works with this
+ release of the driver (see Readme). Also verify
+ that your current kernel version doesn't have more
+ recent sound driver version than this one. IT'S HIGHLY
+ RECOMMENDED THAT YOU USE THE SOUND DRIVER VERSION THAT
+ IS DISTRIBUTED WITH KERNEL SOURCES.
+
+- When installing separately distributed sound driver you should first
+ read the above notice. Then try to find proper directory where and how
+ to install the driver sources. You should not try to install a separately
+ distributed driver version if you are not able to find the proper way
+ yourself (in this case use the version that is distributed with kernel
+ sources). Remove old version of linux/drivers/sound directory before
+ installing new files.
+
+- To build the device files you need to run the enclosed shell script
+ (see below). You need to do this only when installing sound driver
+ first time or when upgrading to much recent version than the earlier
+ one.
+
+- Configure and compile Linux as normally (remember to include the
+ sound support during "make config"). Please refer to kernel documentation
+ for instructions about configuring and compiling kernel. File Readme.cards
+ contains card specific instructions for configuring this driver for
+ use with various sound cards.
+
+Boot time configuration (using lilo and insmod)
+-----------------------------------------------
+
+This information has been removed. Too many users didn't believe
+that it's really not necessary to use this method. Please look at
+Readme of sound driver version 3.0.1 if you still want to use this method.
+
+Problems
+--------
+
+Common error messages:
+
+- /dev/???????: No such file or directory.
+Run the script at the end of this file.
+
+- /dev/???????: No such device.
+You are not running kernel which contains the sound driver. When using
+modularized sound driver this error means that the sound driver is not
+loaded.
+
+- /dev/????: No such device or address.
+Sound driver didn't detect suitable card when initializing. Please look at
+Readme.cards for info about configuring the driver with your card. Also
+check for possible boot (insmod) time error messages in /var/adm/messages.
+
+- Other messages or problems
+Please check http://www.opensound.com/ossfree for more info.
+
+Configuring version 3.8 (for Linux) with some common sound cards
+================================================================
+
+This document describes configuring sound cards with the freeware version of
+Open Sound Systems (OSS/Free). Information about the commercial version
+(OSS/Linux) and its configuration is available from
+http://www.opensound.com/linux.html. Information presented here is
+not valid for OSS/Linux.
+
+If you are unsure about how to configure OSS/Free
+you can download the free evaluation version of OSS/Linux from the above
+address. There is a chance that it can autodetect your sound card. In this case
+you can use the information included in soundon.log when configuring OSS/Free.
+
+
+IMPORTANT! This document covers only cards that were "known" when
+ this driver version was released. Please look at
+ http://www.opensound.com/ossfree for info about
+ cards introduced recently.
+
+ When configuring the sound driver, you should carefully
+ check each sound configuration option (particularly
+ "Support for /dev/dsp and /dev/audio"). The default values
+ offered by these programs are not necessarily valid.
+
+
+THE BIGGEST MISTAKES YOU CAN MAKE
+=================================
+
+1. Assuming that the card is Sound Blaster compatible when it's not.
+--------------------------------------------------------------------
+
+The number one mistake is to assume that your card is compatible with
+Sound Blaster. Only the cards made by Creative Technology or which have
+one or more chips labeled by Creative are SB compatible. In addition there
+are few sound chipsets which are SB compatible in Linux such as ESS1688 or
+Jazz16. Note that SB compatibility in DOS/Windows does _NOT_ mean anything
+in Linux.
+
+IF YOU REALLY ARE 150% SURE YOU HAVE A SOUND BLASTER YOU CAN SKIP THE REST OF
+THIS CHAPTER.
+
+For most other "supposed to be SB compatible" cards you have to use other
+than SB drivers (see below). It is possible to get most sound cards to work
+in SB mode but in general it's a complete waste of time. There are several
+problems which you will encounter by using SB mode with cards that are not
+truly SB compatible:
+
+- The SB emulation is at most SB Pro (DSP version 3.x) which means that
+you get only 8 bit audio (there is always an another ("native") mode which
+gives the 16 bit capability). The 8 bit only operation is the reason why
+many users claim that sound quality in Linux is much worse than in DOS.
+In addition some applications require 16 bit mode and they produce just
+noise with a 8 bit only device.
+- The card may work only in some cases but refuse to work most of the
+time. The SB compatible mode always requires special initialization which is
+done by the DOS/Windows drivers. This kind of cards work in Linux after
+you have warm booted it after DOS but they don't work after cold boot
+(power on or reset).
+- You get the famous "DMA timed out" messages. Usually all SB clones have
+software selectable IRQ and DMA settings. If the (power on default) values
+currently used by the card don't match configuration of the driver you will
+get the above error message whenever you try to record or play. There are
+few other reasons to the DMA timeout message but using the SB mode seems
+to be the most common cause.
+
+2. Trying to use a PnP (Plug & Play) card just like an ordinary sound card
+--------------------------------------------------------------------------
+
+Plug & Play is a protocol defined by Intel and Microsoft. It lets operating
+systems to easily identify and reconfigure I/O ports, IRQs and DMAs of ISA
+cards. The problem with PnP cards is that the standard Linux doesn't currently
+(versions 2.1.x and earlier) don't support PnP. This means that you will have
+to use some special tricks (see later) to get a PnP card alive. Many PnP cards
+work after they have been initialized but this is not always the case.
+
+There are sometimes both PnP and non-PnP versions of the same sound card.
+The non-PnP version is the original model which usually has been discontinued
+more than an year ago. The PnP version has the same name but with "PnP"
+appended to it (sometimes not). This causes major confusion since the non-PnP
+model works with Linux but the PnP one doesn't.
+
+You should carefully check if "Plug & Play" or "PnP" is mentioned in the name
+of the card or in the documentation or package that came with the card.
+Everything described in the rest of this document is not necessarily valid for
+PnP models of sound cards even you have managed to wake up the card properly.
+Many PnP cards are simply too different from their non-PnP ancestors which are
+covered by this document.
+
+
+Cards that are not (fully) supported by this driver
+===================================================
+
+See http://www.opensound.com/ossfree for information about sound cards
+to be supported in future.
+
+
+How to use sound without recompiling kernel and/or sound driver
+===============================================================
+
+There is a commercial sound driver which comes in precompiled form and doesn't
+require recompiling of the kernel. See http://www.4Front-tech.com/oss.html for
+more info.
+
+
+Configuring PnP cards
+=====================
+
+New versions of most sound cards use the so-called ISA PnP protocol for
+soft configuring their I/O, IRQ, DMA and shared memory resources.
+Currently at least cards made by Creative Technology (SB32 and SB32AWE
+PnP), Gravis (GUS PnP and GUS PnP Pro), Ensoniq (Soundscape PnP) and
+Aztech (some Sound Galaxy models) use PnP technology. The CS4232/4236 audio
+chip by Crystal Semiconductor (Intel Atlantis, HP Pavilion and many other
+motherboards) is also based on PnP technology but there is a "native" driver
+available for it (see information about CS4232 later in this document).
+
+PnP sound cards (as well as most other PnP ISA cards) are not supported
+by this version of the driver . Proper
+support for them should be released during 97 once the kernel level
+PnP support is available.
+
+There is a method to get most of the PnP cards to work. The basic method
+is the following:
+
+1) Boot DOS so the card's DOS drivers have a chance to initialize it.
+2) _Cold_ boot to Linux by using "loadlin.exe". Hitting ctrl-alt-del
+works with older machines but causes a hard reset of all cards on recent
+(Pentium) machines.
+3) If you have the sound driver in Linux configured properly, the card should
+work now. "Proper" means that I/O, IRQ and DMA settings are the same as in
+DOS. The hard part is to find which settings were used. See the documentation of
+your card for more info.
+
+Windows 95 could work as well as DOS but running loadlin may be difficult.
+Probably you should "shut down" your machine to MS-DOS mode before running it.
+
+Some machines have a BIOS utility for setting PnP resources. This is a good
+way to configure some cards. In this case you don't need to boot DOS/Win95
+before starting Linux.
+
+Another way to initialize PnP cards without DOS/Win95 is a Linux based
+PnP isolation tool. When writing this there is a pre alpha test version
+of such a tool available from ftp://ftp.demon.co.uk/pub/unix/linux/utils. The
+file is called isapnptools-*. Please note that this tool is just a temporary
+solution which may be incompatible with future kernel versions having proper
+support for PnP cards. There are bugs in setting DMA channels in earlier
+versions of isapnptools so at least version 1.6 is required with sound cards.
+
+Yet another way to use PnP cards is to use (commercial) OSS/Linux drivers. See
+http://www.opensound.com/linux.html for more info. This is probably the way you
+should do it if you don't want to spend time recompiling the kernel and
+required tools.
+
+
+Read this before trying to configure the driver
+===============================================
+
+There are currently many cards that work with this driver. Some of the cards
+have native support while others work since they emulate some other
+card (usually SB, MSS/WSS and/or MPU401). The following cards have native
+support in the driver. Detailed instructions for configuring these cards
+will be given later in this document.
+
+Pro Audio Spectrum 16 (PAS16) and compatibles:
+ Pro Audio Spectrum 16
+ Pro Audio Studio 16
+ Logitech Sound Man 16
+ NOTE! The original Pro Audio Spectrum as well as the PAS+ are not
+ and will not be supported by the driver.
+
+Media Vision Jazz16 based cards
+ Pro Sonic 16
+ Logitech SoundMan Wave
+ (Other Jazz based cards should work but I don't have any reports
+ about them).
+
+Sound Blasters
+ SB 1.0 to 2.0
+ SB Pro
+ SB 16
+ SB32/64/AWE
+ Configure SB32/64/AWE just like SB16. See lowlevel/README.awe
+ for information about using the wave table synth.
+ NOTE! AWE63/Gold and 16/32/AWE "PnP" cards need to be activated
+ using isapnptools before they work with OSS/Free.
+ SB16 compatible cards by other manufacturers than Creative.
+ You have been fooled since there are _no_ SB16 compatible
+ cards on the market (as of May 1997). It's likely that your card
+ is compatible just with SB Pro but there is also a non-SB-
+ compatible 16 bit mode. Usually it's MSS/WSS but it could also
+ be a proprietary one like MV Jazz16 or ESS ES688. OPTi
+ MAD16 chips are very common in so called "SB 16 bit cards"
+ (try with the MAD16 driver).
+
+ ======================================================================
+ "Supposed to be SB compatible" cards.
+ Forget the SB compatibility and check for other alternatives
+ first. The only cards that work with the SB driver in
+ Linux have been made by Creative Technology (there is at least
+ one chip on the card with "CREATIVE" printed on it). The
+ only other SB compatible chips are ESS and Jazz16 chips
+ (maybe ALSxxx chips too but they probably don't work).
+ Most other "16 bit SB compatible" cards such as "OPTi/MAD16" or
+ "Crystal" are _NOT_ SB compatible in Linux.
+
+ Practically all sound cards have some kind of SB emulation mode
+ in addition to their native (16 bit) mode. In most cases this
+ (8 bit only) SB compatible mode doesn't work with Linux. If
+ you get it working it may cause problems with games and
+ applications which require 16 bit audio. Some 16 bit only
+ applications don't check if the card actually supports 16 bits.
+ They just dump 16 bit data to a 8 bit card which produces just
+ noise.
+
+ In most cases the 16 bit native mode is supported by Linux.
+ Use the SB mode with "clones" only if you don't find anything
+ better from the rest of this doc.
+ ======================================================================
+
+Gravis Ultrasound (GUS)
+ GUS
+ GUS + the 16 bit option
+ GUS MAX
+ GUS ACE (No MIDI port and audio recording)
+ GUS PnP (with RAM)
+
+MPU-401 and compatibles
+ The driver works both with the full (intelligent mode) MPU-401
+ cards (such as MPU IPC-T and MQX-32M) and with the UART only
+ dumb MIDI ports. MPU-401 is currently the most common MIDI
+ interface. Most sound cards are compatible with it. However,
+ don't enable MPU401 mode blindly. Many cards with native support
+ in the driver have their own MPU401 driver. Enabling the standard one
+ will cause a conflict with these cards. So check if your card is
+ in the list of supported cards before enabling MPU401.
+
+Windows Sound System (MSS/WSS)
+ Even when Microsoft has discontinued their own Sound System card
+ they managed to make it a standard. MSS compatible cards are based on
+ a codec chip which is easily available from at least two manufacturers
+ (AD1848 by Analog Devices and CS4231/CS4248 by Crystal Semiconductor).
+ Currently most sound cards are based on one of the MSS compatible codec
+ chips. The CS4231 is used in the high quality cards such as GUS MAX,
+ MediaTrix AudioTrix Pro and TB Tropez (GUS MAX is not MSS compatible).
+
+ Having a AD1848, CS4248 or CS4231 codec chip on the card is a good
+ sign. Even if the card is not MSS compatible, it could be easy to write
+ support for it. Note also that most MSS compatible cards
+ require special boot time initialization which may not be present
+ in the driver. Also, some MSS compatible cards have native support.
+ Enabling the MSS support with these cards is likely to
+ cause a conflict. So check if your card is listed in this file before
+ enabling the MSS support.
+
+Yamaha FM synthesizers (OPL2, OPL3 (not OPL3-SA) and OPL4)
+ Most sound cards have a FM synthesizer chip. The OPL2 is a 2
+ operator chip used in the original AdLib card. Currently it's used
+ only in the cheapest (8 bit mono) cards. The OPL3 is a 4 operator
+ FM chip which provides better sound quality and/or more available
+ voices than the OPL2. The OPL4 is a new chip that has an OPL3 and
+ a wave table synthesizer packed onto the same chip. The driver supports
+ just the OPL3 mode directly. Most cards with an OPL4 (like
+ SM Wave and AudioTrix Pro) support the OPL4 mode using MPU401
+ emulation. Writing a native OPL4 support is difficult
+ since Yamaha doesn't give information about their sample ROM chip.
+
+ Enable the generic OPL2/OPL3 FM synthesizer support if your
+ card has a FM chip made by Yamaha. Don't enable it if your card
+ has a software (TRS) based FM emulator.
+
+ ----------------------------------------------------------------
+ NOTE! OPL3-SA is different chip than the ordinary OPL3. In addition
+ to the FM synth this chip has also digital audio (WSS) and
+ MIDI (MPU401) capabilities. Support for OPL3-SA is described below.
+ ----------------------------------------------------------------
+
+Yamaha OPL3-SA1
+
+ Yamaha OPL3-SA1 (YMF701) is an audio controller chip used on some
+ (Intel) motherboards and on cheap sound cards. It should not be
+ confused with the original OPL3 chip (YMF278) which is entirely
+ different chip. OPL3-SA1 has support for MSS, MPU401 and SB Pro
+ (not used in OSS/Free) in addition to the OPL3 FM synth.
+
+ There are also chips called OPL3-SA2, OPL3-SA3, ..., OPL3SA-N. They
+ are PnP chips and will not work with the OPL3-SA1 driver. You should
+ use the standard MSS, MPU401 and OPL3 options with these chips and to
+ activate the card using isapnptools.
+
+4Front Technologies SoftOSS
+
+ SoftOSS is a software based wave table emulation which works with
+ any 16 bit stereo sound card. Due to its nature a fast CPU is
+ required (P133 is minimum). Although SoftOSS does _not_ use MMX
+ instructions it has proven out that recent processors (which appear
+ to have MMX) perform significantly better with SoftOSS than earlier
+ ones. For example a P166MMX beats a PPro200. SoftOSS should not be used
+ on 486 or 386 machines.
+
+ The amount of CPU load caused by SoftOSS can be controlled by
+ selecting the CONFIG_SOFTOSS_RATE and CONFIG_SOFTOSS_VOICES
+ parameters properly (they will be prompted by make config). It's
+ recommended to set CONFIG_SOFTOSS_VOICES to 32. If you have a
+ P166MMX or faster (PPro200 is not faster) you can set
+ CONFIG_SOFTOSS_RATE to 44100 (kHz). However with slower systems it
+ recommended to use sampling rates around 22050 or even 16000 kHz.
+ Selecting too high values for these parameters may hang your
+ system when playing MIDI files with hight degree of polyphony
+ (number of concurrently playing notes). It's also possible to
+ decrease CONFIG_SOFTOSS_VOICES. This makes it possible to use
+ higher sampling rates. However using fewer voices decreases
+ playback quality more than decreasing the sampling rate.
+
+ SoftOSS keeps the samples loaded on the system's RAM so much RAM is
+ required. SoftOSS should never be used on machines with less than 16 MB
+ of RAM since this is potentially dangerous (you may accidentally run out
+ of memory which probably crashes the machine).
+
+ SoftOSS implements the wave table API originally designed for GUS. For
+ this reason all applications designed for GUS should work (at least
+ after minor modifications). For example gmod/xgmod and playmidi -g are
+ known to work.
+
+ To work SoftOSS will require GUS compatible
+ patch files to be installed on the system (in /dos/ultrasnd/midi). You
+ can use the public domain MIDIA patchset available from several ftp
+ sites.
+
+ *********************************************************************
+ IMPORTANT NOTICE! The original patch set distributed with the Gravis
+ Ultrasound card is not in public domain (even though it's available from
+ some FTP sites). You should contact Voice Crystal (www.voicecrystal.com)
+ if you like to use these patches with SoftOSS included in OSS/Free.
+ *********************************************************************
+
+PSS based cards (AD1848 + ADSP-2115 + Echo ESC614 ASIC)
+ Analog Devices and Echo Speech have together defined a sound card
+ architecture based on the above chips. The DSP chip is used
+ for emulation of SB Pro, FM and General MIDI/MT32.
+
+ There are several cards based on this architecture. The most known
+ ones are Orchid SW32 and Cardinal DSP16.
+
+ The driver supports downloading DSP algorithms to these cards.
+
+ NOTE! You will have to use the "old" config script when configuring
+ PSS cards.
+
+MediaTrix AudioTrix Pro
+ The ATP card is built around a CS4231 codec and an OPL4 synthesizer
+ chips. The OPL4 mode is supported by a microcontroller running a
+ General MIDI emulator. There is also a SB 1.5 compatible playback mode.
+
+Ensoniq SoundScape and compatibles
+ Ensoniq has designed a sound card architecture based on the
+ OTTO synthesizer chip used in their professional MIDI synthesizers.
+ Several companies (including Ensoniq, Reveal and Spea) are selling
+ cards based on this architecture.
+
+ NOTE! The SoundScape PnP is not supported by OSS/Free. Ensoniq VIVO and
+ VIVO90 cards are not compatible with Soundscapes so the Soundscape
+ driver will not work with them. You may want to use OSS/Linux with these
+ cards.
+
+OPTi MAD16 and Mozart based cards
+ The Mozart (OAK OTI-601), MAD16 (OPTi 82C928), MAD16 Pro (OPTi 82C929),
+ OPTi 82C924/82C925 (in _non_ PnP mode) and OPTi 82C930 interface
+ chips are used in many different sound cards, including some
+ cards by Reveal miro and Turtle Beach (Tropez). The purpose of these
+ chips is to connect other audio components to the PC bus. The
+ interface chip performs address decoding for the other chips.
+ NOTE! Tropez Plus is not MAD16 but CS4232 based.
+ NOTE! MAD16 PnP cards (82C924, 82C925, 82C931) are not MAD16 compatible
+ in the PnP mode. You will have to use them in MSS mode after having
+ initialized them using isapnptools or DOS. 82C931 probably requires
+ initialization using DOS/Windows (running isapnptools is not enough).
+ It's possible to use 82C931 with OSS/Free by jumpering it to non-PnP
+ mode (provided that the card has a jumper for this). In non-PnP mode
+ 82C931 is compatible with 82C930 and should work with the MAD16 driver
+ (without need to use isapnptools or DOS to initialize it). All OPTi
+ chips are supported by OSS/Linux (both in PnP and non-PnP modes).
+
+Audio Excel DSP16
+ Support for this card was written by Riccardo Faccetti
+ (riccardo@cdc8g5.cdc.polimi.it). The AEDSP16 driver included in
+ the lowlevel/ directory. To use it you should enable the
+ "Additional low level drivers" option.
+
+Crystal CS4232 and CS4236 based cards such as AcerMagic S23, TB Tropez _Plus_ and
+ many PC motherboards (Compaq, HP, Intel, ...)
+ CS4232 is a PnP multimedia chip which contains a CS3231A codec,
+ SB and MPU401 emulations. There is support for OPL3 too.
+ Unfortunately the MPU401 mode doesn't work (I don't know how to
+ initialize it). CS4236 is an enhanced (compatible) version of CS4232.
+ NOTE! Don't ever try to use isapnptools with CS4232 since this will just
+ freeze your machine (due to chip bugs). If you have problems in getting
+ CS4232 working you could try initializing it with DOS (CS4232C.EXE) and
+ then booting Linux using loadlin. CS4232C.EXE loads a secret firmware
+ patch which is not documented by Crystal.
+
+Turtle Beach Maui and Tropez "classic"
+ This driver version supports sample, patch and program loading commands
+ described in the Maui/Tropez User's manual.
+ There is now full initialization support too. The audio side of
+ the Tropez is based on the MAD16 chip (see above).
+ NOTE! Tropez Plus is different card than Tropez "classic" and will not
+ work fully in Linux. You can get audio features working by configuring
+ the card as a CS4232 based card (above).
+
+
+Jumpers and software configuration
+==================================
+
+Some of the earliest sound cards were jumper configurable. You have to
+configure the driver use I/O, IRQ and DMA settings
+that match the jumpers. Just few 8 bit cards are fully jumper
+configurable (SB 1.x/2.x, SB Pro and clones).
+Some cards made by Aztech have an EEPROM which contains the
+config info. These cards behave much like hardware jumpered cards.
+
+Most cards have jumper for the base I/O address but other parameters
+are software configurable. Sometimes there are few other jumpers too.
+
+Latest cards are fully software configurable or they are PnP ISA
+compatible. There are no jumpers on the board.
+
+The driver handles software configurable cards automatically. Just configure
+the driver to use I/O, IRQ and DMA settings which are known to work.
+You could usually use the same values than with DOS and/or Windows.
+Using different settings is possible but not recommended since it may cause
+some trouble (for example when warm booting from an OS to another or
+when installing new hardware to the machine).
+
+Sound driver sets the soft configurable parameters of the card automatically
+during boot. Usually you don't need to run any extra initialization
+programs when booting Linux but there are some exceptions. See the
+card-specific instructions below for more info.
+
+The drawback of software configuration is that the driver needs to know
+how the card must be initialized. It cannot initialize unknown cards
+even if they are otherwise compatible with some other cards (like SB,
+MPU401 or Windows Sound System).
+
+
+What if your card was not listed above?
+=======================================
+
+The first thing to do is to look at the major IC chips on the card.
+Many of the latest sound cards are based on some standard chips. If you
+are lucky, all of them could be supported by the driver. The most common ones
+are the OPTi MAD16, Mozart, SoundScape (Ensoniq) and the PSS architectures
+listed above. Also look at the end of this file for list of unsupported
+cards and the ones which could be supported later.
+
+The last resort is to send _exact_ name and model information of the card
+to me together with a list of the major IC chips (manufactured, model) to
+me. I could then try to check if your card looks like something familiar.
+
+There are many more cards in the world than listed above. The first thing to
+do with these cards is to check if they emulate some other card or interface
+such as SB, MSS and/or MPU401. In this case there is a chance to get the
+card to work by booting DOS before starting Linux (boot DOS, hit ctrl-alt-del
+and boot Linux without hard resetting the machine). In this method the
+DOS based driver initializes the hardware to use known I/O, IRQ and DMA
+settings. If sound driver is configured to use the same settings, everything
+should work OK.
+
+
+Configuring sound driver (with Linux)
+=====================================
+
+The sound driver is currently distributed as part of the Linux kernel. The
+files are in /usr/src/linux/drivers/sound/.
+
+****************************************************************************
+* ALWAYS USE THE SOUND DRIVER VERSION WHICH IS DISTRIBUTED WITH *
+* THE KERNEL SOURCE PACKAGE YOU ARE USING. SOME ALPHA AND BETA TEST *
+* VERSIONS CAN BE INSTALLED FROM A SEPARATELY DISTRIBUTED PACKAGE *
+* BUT CHECK THAT THE PACKAGE IS NOT MUCH OLDER (OR NEWER) THAN THE *
+* KERNEL YOU ARE USING. IT'S POSSIBLE THAT THE KERNEL/DRIVER *
+* INTERFACE CHANGES BETWEEN KERNEL RELEASES WHICH MAY CAUSE SOME *
+* INCOMPATIBILITY PROBLEMS. *
+* *
+* IN CASE YOU INSTALL A SEPARATELY DISTRIBUTED SOUND DRIVER VERSION, *
+* BE SURE TO REMOVE OR RENAME THE OLD SOUND DRIVER DIRECTORY BEFORE *
+* INSTALLING THE NEW ONE. LEAVING OLD FILES TO THE SOUND DRIVER *
+* DIRECTORY _WILL_ CAUSE PROBLEMS WHEN THE DRIVER IS USED OR *
+* COMPILED. *
+****************************************************************************
+
+To configure the driver, run "make config" in the kernel source directory
+(/usr/src/linux). Answer "y" or "m" to the question about Sound card support
+(after the questions about mouse, CD-ROM, ftape, etc. support). Questions
+about options for sound will then be asked.
+
+After configuring the kernel and sound driver and compile the kernel
+following instructions in the kernel README.
+
+The sound driver configuration dialog
+-------------------------------------
+
+Sound configuration starts by making some yes/no questions. Be careful
+when answering to these questions since answering y to a question may
+prevent some later ones from being asked. For example don't answer y to
+the first question (PAS16) if you don't really have a PAS16. Don't enable
+more cards than you really need since they just consume memory. Also
+some drivers (like MPU401) may conflict with your SCSI controller and
+prevent kernel from booting. If you card was in the list of supported
+cards (above), please look at the card specific config instructions
+(later in this file) before starting to configure. Some cards must be
+configured in way which is not obvious.
+
+So here is the beginning of the config dialog. Answer 'y' or 'n' to these
+questions. The default answer is shown so that (y/n) means 'y' by default and
+(n/y) means 'n'. To use the default value, just hit ENTER. But be careful
+since using the default _doesn't_ guarantee anything.
+
+Note also that all questions may not be asked. The configuration program
+may disable some questions depending on the earlier choices. It may also
+select some options automatically as well.
+
+ "ProAudioSpectrum 16 support",
+ - Answer 'y'_ONLY_ if you have a Pro Audio Spectrum _16_,
+ Pro Audio Studio 16 or Logitech SoundMan 16 (be sure that
+ you read the above list correctly). Don't answer 'y' if you
+ have some other card made by Media Vision or Logitech since they
+ are not PAS16 compatible.
+ NOTE! Since 3.5-beta10 you need to enable SB support (next question)
+ if you want to use the SB emulation of PAS16. It's also possible to
+ the emulation if you want to use a true SB card together with PAS16
+ (there is another question about this that is asked later).
+ "Sound Blaster support",
+ - Answer 'y' if you have an original SB card made by Creative Labs
+ or a full 100% hardware compatible clone (like Thunderboard or
+ SM Games). If your card was in the list of supported cards (above),
+ please look at the card specific instructions later in this file
+ before answering this question. For an unknown card you may answer
+ 'y' if the card claims to be SB compatible.
+ Enable this option also with PAS16 (changed since v3.5-beta9).
+
+ Don't enable SB if you have a MAD16 or Mozart compatible card.
+
+ "Generic OPL2/OPL3 FM synthesizer support",
+ - Answer 'y' if your card has a FM chip made by Yamaha (OPL2/OPL3/OPL4).
+ Answering 'y' is usually a safe and recommended choice. However some
+ cards may have software (TSR) FM emulation. Enabling FM support
+ with these cards may cause trouble. However I don't currently know
+ such cards.
+ "Gravis Ultrasound support",
+ - Answer 'y' if you have GUS or GUS MAX. Answer 'n' if you don't
+ have GUS since the GUS driver consumes much memory.
+ Currently I don't have experiences with the GUS ACE so I don't
+ know what to answer with it.
+ "MPU-401 support (NOT for SB16)",
+ - Be careful with this question. The MPU401 interface is supported
+ by almost any sound card today. However some natively supported cards
+ have their own driver for MPU401. Enabling the MPU401 option with
+ these cards will cause a conflict. Also enabling MPU401 on a system
+ that doesn't really have a MPU401 could cause some trouble. If your
+ card was in the list of supported cards (above), please look at
+ the card specific instructions later in this file.
+
+ In MOST cases this MPU401 driver should only be used with "true"
+ MIDI-only MPU401 professional cards. In most other cases there
+ is another way to get the MPU401 compatible interface of a
+ sound card to work.
+ Support for the MPU401 compatible MIDI port of SB16, ESS1688
+ and MV Jazz16 cards is included in the SB driver. Use it instead
+ of this separate MPU401 driver with these cards. As well
+ Soundscape, PSS and Maui drivers include their own MPU401
+ options.
+
+ It's safe to answer 'y' if you have a true MPU401 MIDI interface
+ card.
+ "6850 UART Midi support",
+ - It's safe to answer 'n' to this question in all cases. The 6850
+ UART interface is so rarely used.
+ "PSS (ECHO-ADI2111) support",
+ - Answer 'y' only if you have Orchid SW32, Cardinal DSP16 or some
+ other card based on the PSS chipset (AD1848 codec + ADSP-2115
+ DSP chip + Echo ESC614 ASIC CHIP).
+ "16 bit sampling option of GUS (_NOT_ GUS MAX)",
+ - Answer 'y' if you have installed the 16 bit sampling daughtercard
+ to your GUS. Answer 'n' if you have GUS MAX. Enabling this option
+ disables GUS MAX support.
+ "GUS MAX support",
+ - Answer 'y' only if you have a GUS MAX.
+ "Microsoft Sound System support",
+ - Again think carefully before answering 'y' to this question. It's
+ safe to answer 'y' in case you have the original Windows Sound
+ System card made by Microsoft or Aztech SG 16 Pro (or NX16 Pro).
+ Also you may answer 'y' in case your card was not listed earlier
+ in this file. For cards having native support in the driver, consult
+ the card specific instructions later in this file. Some drivers
+ have their own MSS support and enabling this option will cause a
+ conflict.
+ Note! The MSS driver permits configuring two DMA channels. This is a
+ "nonstandard" feature and works only with very few cards (if any).
+ In most cases the second DMA channel should be disabled or set to
+ the same channel than the first one. Trying to configure two separate
+ channels with cards that don't support this feature will prevent
+ audio (at least recording) from working.
+ "Ensoniq Soundscape support",
+ - Answer 'y' if you have a sound card based on the Ensoniq SoundScape
+ chipset. Such cards are being manufactured at least by Ensoniq,
+ Spea and Reveal (note that Reveal makes other cards also). The oldest
+ cards made by Spea don't work properly with Linux.
+ Soundscape PnP as well as Ensoniq VIVO work only with the commercial
+ OSS/Linux version.
+ "MediaTrix AudioTrix Pro support",
+ - Answer 'y' if you have the AudioTrix Pro.
+ "Support for MAD16 and/or Mozart based cards",
+ - Answer y if your card has a Mozart (OAK OTI-601) or MAD16
+ (OPTi 82C928, 82C929, 82C924/82C925 or 82C930) audio interface chip.
+ These chips are
+ currently quite common so it's possible that many no-name cards
+ have one of them. In addition the MAD16 chip is used in some
+ cards made by known manufacturers such as Turtle Beach (Tropez),
+ Reveal (some models) and Diamond (some recent models).
+ Note OPTi 82C924 and 82C925 are MAD16 compatible only in non PnP
+ mode (jumper selectable on many cards).
+ "Support for TB Maui"
+ - This enables TB Maui specific initialization. Works with TB Maui
+ and TB Tropez (may not work with Tropez Plus).
+
+
+Then the configuration program asks some y/n questions about the higher
+level services. It's recommended to answer 'y' to each of these questions.
+Answer 'n' only if you know you will not need the option.
+
+ "MIDI interface support",
+ - Answering 'n' disables /dev/midi## devices and access to any
+ MIDI ports using /dev/sequencer and /dev/music. This option
+ also affects any MPU401 and/or General MIDI compatible devices.
+ "FM synthesizer (YM3812/OPL-3) support",
+ - Answer 'y' here.
+ "/dev/sequencer support",
+ - Answering 'n' disables /dev/sequencer and /dev/music.
+
+Entering the I/O, IRQ and DMA config parameters
+-----------------------------------------------
+
+After the above questions the configuration program prompts for the
+card specific configuration information. Usually just a set of
+I/O address, IRQ and DMA numbers are asked. With some cards the program
+asks for some files to be used during initialization of the card. For example
+many cards have a DSP chip or microprocessor which must be initialized by
+downloading a program (microcode) file to the card.
+
+Instructions for answering these questions are given in the next section.
+
+
+Card specific information
+=========================
+
+This section gives additional instructions about configuring some cards.
+Please refer manual of your card for valid I/O, IRQ and DMA numbers. Using
+the same settings with DOS/Windows and Linux is recommended. Using
+different values could cause some problems when switching between
+different operating systems.
+
+Sound Blasters (the original ones by Creative)
+---------------------------------------------
+
+NOTE! Check if you have a PnP Sound Blaster (cards sold after summer 1995
+ are almost certainly PnP ones). With PnP cards you should use isapnptools
+ to activate them (see above).
+
+It's possible to configure these cards to use different I/O, IRQ and
+DMA settings. Since the possible/default settings have changed between various
+models, you have to consult manual of your card for the proper ones. It's
+a good idea to use the same values than with DOS/Windows. With SB and SB Pro
+it's the only choice. SB16 has software selectable IRQ and DMA channels but
+using different values with DOS and Linux is likely to cause troubles. The
+DOS driver is not able to reset the card properly after warm boot from Linux
+if Linux has used different IRQ or DMA values.
+
+The original (steam) Sound Blaster (versions 1.x and 2.x) use always
+DMA1. There is no way to change it.
+
+The SB16 needs two DMA channels. A 8 bit one (1 or 3) is required for
+8 bit operation and a 16 bit one (5, 6 or 7) for the 16 bit mode. In theory
+it's possible to use just one (8 bit) DMA channel by answering the 8 bit
+one when the configuration program asks for the 16 bit one. This may work
+in some systems but is likely to cause terrible noise on some other systems.
+
+It's possible to use two SB16/32/64 at the same time. To do this you should
+first configure OSS/Free for one card. Then edit local.h manually and define
+SB2_BASE, SB2_IRQ, SB2_DMA and SB2_DMA2 for the second one. You can't get
+the OPL3, MIDI and EMU8000 devices of the second card to work. If you are
+going to use two PnP Sound Blasters, ensure that they are of different model
+and have different PnP IDs. There is no way to get two cards with the same
+card ID and serial number to work. The easiest way to check this is trying
+if isapnptools can see both cards or just one.
+
+NOTE! Don't enable the SM Games option (asked by the configuration program)
+ if you are not 101% sure that your card is a Logitech Soundman Games
+ (not a SM Wave or SM16).
+
+SB Clones
+---------
+
+First of all: There are no SB16 clones. There are SB Pro clones with a
+16 bit mode which is not SB16 compatible. The most likely alternative is that
+the 16 bit mode means MSS/WSS.
+
+There are just a few fully 100% hardware SB or SB Pro compatible cards.
+I know just Thunderboard and SM Games. Other cards require some kind of
+hardware initialization before they become SB compatible. Check if your card
+was listed in the beginning of this file. In this case you should follow
+instructions for your card later in this file.
+
+For other not fully SB clones you may try initialization using DOS in
+the following way:
+
+ - Boot DOS so that the card specific driver gets run.
+ - Hit ctrl-alt-del (or use loadlin) to boot Linux. Don't
+ switch off power or press the reset button.
+ - If you use the same I/O, IRQ and DMA settings in Linux, the
+ card should work.
+
+If your card is both SB and MSS compatible, I recommend using the MSS mode.
+Most cards of this kind are not able to work in the SB and the MSS mode
+simultaneously. Using the MSS mode provides 16 bit recording and playback.
+
+ProAudioSpectrum 16 and compatibles
+-----------------------------------
+
+PAS16 has a SB emulation chip which can be used together with the native
+(16 bit) mode of the card. To enable this emulation you should configure
+the driver to have SB support too (this has been changed since version
+3.5-beta9 of this driver).
+
+With current driver versions it's also possible to use PAS16 together with
+another SB compatible card. In this case you should configure SB support
+for the other card and to disable the SB emulation of PAS16 (there is a
+separate questions about this).
+
+With PAS16 you can use two audio device files at the same time. /dev/dsp (and
+/dev/audio) is connected to the 8/16 bit native codec and the /dev/dsp1 (and
+/dev/audio1) is connected to the SB emulation (8 bit mono only).
+
+Gravis Ultrasound
+-----------------
+
+There are many different revisions of the Ultrasound card (GUS). The
+earliest ones (pre 3.7) don't have a hardware mixer. With these cards
+the driver uses a software emulation for synth and pcm playbacks. It's
+also possible to switch some of the inputs (line in, mic) off by setting
+mixer volume of the channel level below 10%. For recording you have
+to select the channel as a recording source and to use volume above 10%.
+
+GUS 3.7 has a hardware mixer.
+
+GUS MAX and the 16 bit sampling daughtercard have a CS4231 codec chip which
+also contains a mixer.
+
+Configuring GUS is simple. Just enable the GUS support and GUS MAX or
+the 16 bit daughtercard if you have them. Note that enabling the daughter
+card disables GUS MAX driver.
+
+NOTE for owners of the 16 bit daughtercard: By default the daughtercard
+uses /dev/dsp (and /dev/audio). Command "ln -sf /dev/dsp1 /dev/dsp"
+selects the daughter card as the default device.
+
+With just the standard GUS enabled the configuration program prompts
+for the I/O, IRQ and DMA numbers for the card. Use the same values than
+with DOS.
+
+With the daughter card option enabled you will be prompted for the I/O,
+IRQ and DMA numbers for the daughter card. You have to use different I/O
+and DMA values than for the standard GUS. The daughter card permits
+simultaneous recording and playback. Use /dev/dsp (the daughtercard) for
+recording and /dev/dsp1 (GUS GF1) for playback.
+
+GUS MAX uses the same I/O address and IRQ settings than the original GUS
+(GUS MAX = GUS + a CS4231 codec). In addition an extra DMA channel may be used.
+Using two DMA channels permits simultaneous playback using two devices
+(dev/dsp0 and /dev/dsp1). The second DMA channel is required for
+full duplex audio.
+To enable the second DMA channels, give a valid DMA channel when the config
+program asks for the GUS MAX DMA (entering -1 disables the second DMA).
+Using 16 bit DMA channels (5,6 or 7) is recommended.
+
+If you have problems in recording with GUS MAX, you could try to use
+just one 8 bit DMA channel. Recording will not work with one DMA
+channel if it's a 16 bit one.
+
+Microphone input of GUS MAX is connected to mixer in little bit nonstandard
+way. There is actually two microphone volume controls. Normal "mic" controls
+only recording level. Mixer control "speaker" is used to control volume of
+microphone signal connected directly to line/speaker out. So just decrease
+volume of "speaker" if you have problems with microphone feedback.
+
+GUS ACE works too but any attempt to record or to use the MIDI port
+will fail.
+
+GUS PnP (with RAM) is partially supported but it needs to be initialized using
+DOS or isapnptools before starting the driver.
+
+MPU401 and Windows Sound System
+-------------------------------
+
+Again. Don't enable these options in case your card is listed
+somewhere else in this file.
+
+Configuring these cards is obvious (or it should be). With MSS
+you should probably enable the OPL3 synth also since
+most MSS compatible cards have it. However check that this is true
+before enabling OPL3.
+
+Sound driver supports more than one MPU401 compatible cards at the same time
+but the config program asks config info for just the first of them.
+Adding the second or third MPU interfaces must be done manually by
+editing sound/local.h (after running the config program). Add defines for
+MPU2_BASE & MPU2_IRQ (and MPU3_BASE & MPU3_IRQ) to the file.
+
+CAUTION!
+
+The default I/O base of Adaptec AHA-1542 SCSI controller is 0x330 which
+is also the default of the MPU401 driver. Don't configure the sound driver to
+use 0x330 as the MPU401 base if you have a AHA1542. The kernel will not boot
+if you make this mistake.
+
+PSS
+---
+
+Even the PSS cards are compatible with SB, MSS and MPU401, you must not
+enable these options when configuring the driver. The configuration
+program handles these options itself. (You may use the SB, MPU and MSS options
+together with PSS if you have another card on the system).
+
+The PSS driver enables MSS and MPU401 modes of the card. SB is not enabled
+since it doesn't work concurrently with MSS. The driver loads also a
+DSP algorithm which is used to for the general MIDI emulation. The
+algorithm file (.ld) is read by the config program and written to a
+file included when the pss.c is compiled. For this reason the config
+program asks if you want to download the file. Use the genmidi.ld file
+distributed with the DOS/Windows drivers of the card (don't use the mt32.ld).
+With some cards the file is called 'synth.ld'. You must have access to
+the file when configuring the driver. The easiest way is to mount the DOS
+partition containing the file with Linux.
+
+It's possible to load your own DSP algorithms and run them with the card.
+Look at the directory pss_test of snd-util-3.0.tar.gz for more info.
+
+AudioTrix Pro
+-------------
+
+You have to enable the OPL3 and SB (not SB Pro or SB16) drivers in addition
+to the native AudioTrix driver. Don't enable MSS or MPU drivers.
+
+Configuring ATP is little bit tricky since it uses so many I/O, IRQ and
+DMA numbers. Using the same values than with DOS/Win is a good idea. Don't
+attempt to use the same IRQ or DMA channels twice.
+
+The SB mode of ATP is implemented so the ATP driver just enables SB
+in the proper address. The SB driver handles the rest. You have to configure
+both the SB driver and the SB mode of ATP to use the same IRQ, DMA and I/O
+settings.
+
+Also the ATP has a microcontroller for the General MIDI emulation (OPL4).
+For this reason the driver asks for the name of a file containing the
+microcode (TRXPRO.HEX). This file is usually located in the directory
+where the DOS drivers were installed. You must have access to this file
+when configuring the driver.
+
+If you have the effects daughtercard, it must be initialized by running
+the setfx program of snd-util-3.0.tar.gz package. This step is not required
+when using the (future) binary distribution version of the driver.
+
+Ensoniq SoundScape
+------------------
+
+NOTE! The new PnP SoundScape is not supported yet. Soundscape compatible
+ cards made by Reveal don't work with Linux. They use older revision
+ of the Soundscape chipset which is not fully compatible with
+ newer cards made by Ensoniq.
+
+The SoundScape driver handles initialization of MSS and MPU supports
+itself so you don't need to enable other drivers than SoundScape
+(enable also the /dev/dsp, /dev/sequencer and MIDI supports).
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!!!!! !!!!
+!!!!! NOTE! Before version 3.5-beta6 there WERE two sets of audio !!!!
+!!!!! device files (/dev/dsp0 and /dev/dsp1). The first one WAS !!!!
+!!!!! used only for card initialization and the second for audio !!!!
+!!!!! purposes. It WAS required to change /dev/dsp (a symlink) to !!!!
+!!!!! point to /dev/dsp1. !!!!
+!!!!! !!!!
+!!!!! This is not required with OSS versions 3.5-beta6 and later !!!!
+!!!!! since there is now just one audio device file. Please !!!!
+!!!!! change /dev/dsp to point back to /dev/dsp0 if you are !!!!
+!!!!! upgrading from an earlier driver version using !!!!
+!!!!! (cd /dev;rm dsp;ln -s dsp0 dsp). !!!!
+!!!!! !!!!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The configuration program asks one DMA channel and two interrupts. One IRQ
+and one DMA is used by the MSS codec. The second IRQ is required for the
+MPU401 mode (you have to use different IRQs for both purposes).
+There were earlier two DMA channels for SoundScape but the current driver
+version requires just one.
+
+The SoundScape card has a Motorola microcontroller which must initialized
+_after_ boot (the driver doesn't initialize it during boot).
+The initialization is done by running the 'ssinit' program which is
+distributed in the snd-util-3.0.tar.gz package. You have to edit two
+defines in the ssinit.c and then compile the program. You may run ssinit
+manually (after each boot) or add it to /etc/rc.d/rc.local.
+
+The ssinit program needs the microcode file that comes with the DOS/Windows
+driver of the card. You will need to use version 1.30.00 or later
+of the microcode file (sndscape.co0 or sndscape.co1 depending on
+your card model). THE OLD sndscape.cod WILL NOT WORK. IT WILL HANG YOUR
+MACHINE. The only way to get the new microcode file is to download
+and install the DOS/Windows driver from ftp://ftp.ensoniq.com/pub.
+
+Then you have to select the proper microcode file to use: soundscape.co0
+is the right one for most cards and sndscape.co1 is for few (older) cards
+made by Reveal and/or Spea. The driver has capability to detect the card
+version during boot. Look at the boot log messages in /var/adm/messages
+and locate the sound driver initialization message for the SoundScape
+card. If the driver displays string <Ensoniq Soundscape (old)>, you have
+an old card and you will need to use sndscape.co1. For other cards use
+soundscape.co0. New Soundscape revisions such as Elite and PnP use
+code files with higher numbers (.co2, .co3, etc.).
+
+NOTE! Ensoniq Soundscape VIVO is not compatible with other Soundscape cards.
+ Currently it's possible to use it in Linux only with OSS/Linux
+ drivers.
+
+Check /var/adm/messages after running ssinit. The driver prints
+the board version after downloading the microcode file. That version
+number must match the number in the name of the microcode file (extension).
+
+Running ssinit with a wrong version of the sndscape.co? file is not
+dangerous as long as you don't try to use a file called sndscape.cod.
+If you have initialized the card using a wrong microcode file (sounds
+are terrible), just modify ssinit.c to use another microcode file and try
+again. It's possible to use an earlier version of sndscape.co[01] but it
+may sound weird.
+
+MAD16 (Pro) and Mozart
+----------------------
+
+You need to enable just the MAD16 /Mozart support when configuring
+the driver. _Don't_ enable SB, MPU401 or MSS. However you will need the
+/dev/audio, /dev/sequencer and MIDI supports.
+
+Mozart and OPTi 82C928 (the original MAD16) chips don't support
+MPU401 mode so enter just 0 when the configuration program asks the
+MPU/MIDI I/O base. The MAD16 Pro (OPTi 82C929) and 82C930 chips have MPU401
+mode.
+
+TB Tropez is based on the 82C929 chip. It has two MIDI ports.
+The one connected to the MAD16 chip is the second one (there is a second
+MIDI connector/pins somewhere??). If you have not connected the second MIDI
+port, just disable the MIDI port of MAD16. The 'Maui' compatible synth of
+Tropez is jumper configurable and not connected to the MAD16 chip (the
+Maui driver can be used with it).
+
+Some MAD16 based cards may cause feedback, whistle or terrible noise if the
+line3 mixer channel is turned too high. This happens at least with Shuttle
+Sound System. Current driver versions set volume of line3 low enough so
+this should not be a problem.
+
+If you have a MAD16 card which have an OPL4 (FM + Wave table) synthesizer
+chip (_not_ an OPL3), you have to append a line containing #define MAD16_OPL4
+to the file linux/drivers/sound/local.h (after running make config).
+
+MAD16 cards having a CS4231 codec support full duplex mode. This mode
+can be enabled by configuring the card to use two DMA channels. Possible
+DMA channel pairs are: 0&1, 1&0 and 3&0.
+
+NOTE! Cards having an OPTi 82C924/82C925 chip work with OSS/Free only in
+non-PnP mode (usually jumper selectable). The PnP mode is supported only
+by OSS/Linux.
+
+MV Jazz (ProSonic)
+------------------
+
+The Jazz16 driver is just a hack made to the SB Pro driver. However it works
+fairly well. You have to enable SB, SB Pro (_not_ SB16) and MPU401 supports
+when configuring the driver. The configuration program asks later if you
+want support for MV Jazz16 based cards (after asking SB base address). Answer
+'y' here and the driver asks the second (16 bit) DMA channel.
+
+The Jazz16 driver uses the MPU401 driver in a way which will cause
+problems if you have another MPU401 compatible card. In this case you must
+give address of the Jazz16 based MPU401 interface when the config
+program prompts for the MPU401 information. Then look at the MPU401
+specific section for instructions about configuring more than one MPU401 cards.
+
+Logitech Soundman Wave
+----------------------
+
+Read the above MV Jazz specific instructions first.
+
+The Logitech SoundMan Wave (don't confuse this with the SM16 or SM Games) is
+a MV Jazz based card which has an additional OPL4 based wave table
+synthesizer. The OPL4 chip is handled by an on board microcontroller
+which must be initialized during boot. The config program asks if
+you have a SM Wave immediately after asking the second DMA channel of jazz16.
+If you answer 'y', the config program will ask name of the file containing
+code to be loaded to the microcontroller. The file is usually called
+MIDI0001.BIN and it's located in the DOS/Windows driver directory. The file
+may also be called as TSUNAMI.BIN or something else (older cards?).
+
+The OPL4 synth will be inaccessible without loading the microcontroller code.
+
+Also remember to enable SB MPU401 support if you want to use the OPL4 mode.
+(Don't enable the 'normal' MPU401 device as with some earlier driver
+versions (pre 3.5-alpha8)).
+
+NOTE! Don't answer 'y' when the driver asks about SM Games support
+ (the next question after the MIDI0001.BIN name). However
+ answering 'y' doesn't cause damage your computer so don't panic.
+
+Sound Galaxies
+--------------
+
+There are many different Sound Galaxy cards made by Aztech. The 8 bit
+ones are fully SB or SB Pro compatible and there should be no problems
+with them.
+
+The older 16 bit cards (SG Pro16, SG NX Pro16, Nova and Lyra) have
+an EEPROM chip for storing the configuration data. There is a microcontroller
+which initializes the card to match the EEPROM settings when the machine
+is powered on. These cards actually behave just like they have jumpers
+for all of the settings. Configure driver for MSS, MPU, SB/SB Pro and OPL3
+supports with these cards.
+
+There are some new Sound Galaxies in the market. I have no experience with
+them so read the card's manual carefully.
+
+ESS ES1688 and ES688 'AudioDrive' based cards
+---------------------------------------------
+
+Support for these two ESS chips is embedded in the SB driver.
+Configure these cards just like SB. Enable the 'SB MPU401 MIDI port'
+if you want to use MIDI features of ES1688. ES688 doesn't have MPU mode
+so you don't need to enable it (the driver uses normal SB MIDI automatically
+with ES688).
+
+NOTE! ESS cards are not compatible with MSS/WSS so don't worry if MSS support
+of OSS doesn't work with it.
+
+There are some ES1688/688 based sound cards and (particularly) motherboards
+which use software configurable I/O port relocation feature of the chip.
+This ESS proprietary feature is supported only by OSS/Linux.
+
+There are ES1688 based cards which use different interrupt pin assignment than
+recommended by ESS (5, 7, 9/2 and 10). In this case all IRQs don't work.
+At least a card called (Pearl?) Hypersound 16 supports IRQ 15 but it doesn't
+work.
+
+ES1868 is a PnP chip which is (supposed to be) compatible with ESS1688
+probably works with OSS/Free after initialization using isapnptools.
+
+Reveal cards
+------------
+
+There are several different cards made/marketed by Reveal. Some of them
+are compatible with SoundScape and some use the MAD16 chip. You may have
+to look at the card and try to identify its origin.
+
+Diamond
+-------
+
+The oldest (Sierra Aria based) sound cards made by Diamond are not supported
+(they may work if the card is initialized using DOS). The recent (LX?)
+models are based on the MAD16 chip which is supported by the driver.
+
+Audio Excel DSP16
+-----------------
+
+Support for this card is currently not functional. A new driver for it
+should be available later this year.
+
+PCMCIA cards
+------------
+
+Sorry, can't help. Some cards may work and some don't.
+
+TI TM4000M notebooks
+--------------------
+
+These computers have a built in sound support based on the Jazz chipset.
+Look at the instructions for MV Jazz (above). It's also important to note
+that there is something wrong with the mouse port and sound at least on
+some TM models. Don't enable the "C&T 82C710 mouse port support" when
+configuring Linux. Having it enabled is likely to cause mysterious problems
+and kernel failures when sound is used.
+
+miroSOUND
+---------
+
+The miroSOUND PCM1-pro, PCM12 and PCM20 radio has been used
+successfully. These cards are based on the MAD16, OPL4, and CS4231A chips
+and everything said in the section about MAD16 cards applies here,
+too. The only major difference between the PCMxx and other MAD16 cards
+is that instead of the mixer in the CS4231 codec a separate mixer
+controlled by an on-board 80C32 microcontroller is used. Control of
+the mixer takes place via the ACI (miro's audio control interface)
+protocol that is implemented in a separate lowlevel driver. Make sure
+you compile this ACI driver together with the normal MAD16 support
+when you use a miroSOUND PCMxx card. The ACI mixer is controlled by
+/dev/mixer and the CS4231 mixer by /dev/mixer1 (depends on load
+time). Only in special cases you want to change something regularly on
+the CS4231 mixer.
+
+The miroSOUND PCM12 and PCM20 radio is capable of full duplex
+operation (simultaneous PCM replay and recording), which allows you to
+implement nice real-time signal processing audio effect software and
+network telephones. The ACI mixer has to be switched into the "solo"
+mode for duplex operation in order to avoid feedback caused by the
+mixer (input hears output signal). You can de-/activate this mode
+through toggleing the record button for the wave controller with an
+OSS-mixer.
+
+The PCM20 contains a radio tuner, which is also controlled by
+ACI. This radio tuner is supported by the ACI driver together with the
+miropcm20.o module. Also the 7-band equalizer is integrated
+(limited by the OSS-design). Developement has started and maybe
+finished for the RDS decoder on this card, too. You will be able to
+read RadioText, the Programme Service name, Programme TYpe and
+others. Even the v4l radio module benefits from it with a refined
+strength value. See aci.[ch] and miropcm20*.[ch] for more details.
+
+The following configuration parameters have worked fine for the PCM12
+in Markus Kuhn's system, many other configurations might work, too:
+CONFIG_MAD16_BASE=0x530, CONFIG_MAD16_IRQ=11, CONFIG_MAD16_DMA=3,
+CONFIG_MAD16_DMA2=0, CONFIG_MAD16_MPU_BASE=0x330, CONFIG_MAD16_MPU_IRQ=10,
+DSP_BUFFSIZE=65536, SELECTED_SOUND_OPTIONS=0x00281000.
+
+Bas van der Linden is using his PCM1-pro with a configuration that
+differs in: CONFIG_MAD16_IRQ=7, CONFIG_MAD16_DMA=1, CONFIG_MAD16_MPU_IRQ=9
+
+Compaq Deskpro XL
+-----------------
+
+The builtin sound hardware of Compaq Deskpro XL is now supported.
+You need to configure the driver with MSS and OPL3 supports enabled.
+In addition you need to manually edit linux/drivers/sound/local.h and
+to add a line containing "#define DESKPROXL" if you used
+make menuconfig/xconfig.
+
+Others?
+-------
+
+Since there are so many different sound cards, it's likely that I have
+forgotten to mention many of them. Please inform me if you know yet another
+card which works with Linux, please inform me (or is anybody else
+willing to maintain a database of supported cards (just like in XF86)?).
+
+Cards not supported yet
+=======================
+
+Please check the version of sound driver you are using before
+complaining that your card is not supported. It's possible you are
+using a driver version which was released months before your card was
+introduced.
+
+First of all, there is an easy way to make most sound cards work with Linux.
+Just use the DOS based driver to initialize the card to a known state, then use
+loadlin.exe to boot Linux. If Linux is configured to use the same I/O, IRQ and
+DMA numbers as DOS, the card could work.
+(ctrl-alt-del can be used in place of loadlin.exe but it doesn't work with
+new motherboards). This method works also with all/most PnP sound cards.
+
+Don't get fooled with SB compatibility. Most cards are compatible with
+SB but that may require a TSR which is not possible with Linux. If
+the card is compatible with MSS, it's a better choice. Some cards
+don't work in the SB and MSS modes at the same time.
+
+Then there are cards which are no longer manufactured and/or which
+are relatively rarely used (such as the 8 bit ProAudioSpectrum
+models). It's extremely unlikely that such cards ever get supported.
+Adding support for a new card requires much work and increases time
+required in maintaining the driver (some changes need to be done
+to all low level drivers and be tested too, maybe with multiple
+operating systems). For this reason I have made a decision to not support
+obsolete cards. It's possible that someone else makes a separately
+distributed driver (diffs) for the card.
+
+Writing a driver for a new card is not possible if there are no
+programming information available about the card. If you don't
+find your new card from this file, look from the home page
+(http://www.opensound.com/ossfree). Then please contact
+manufacturer of the card and ask if they have (or are willing to)
+released technical details of the card. Do this before contacting me. I
+can only answer 'no' if there are no programming information available.
+
+I have made decision to not accept code based on reverse engineering
+to the driver. There are three main reasons: First I don't want to break
+relationships to sound card manufacturers. The second reason is that
+maintaining and supporting a driver without any specs will be a pain.
+The third reason is that companies have freedom to refuse selling their
+products to other than Windows users.
+
+Some companies don't give low level technical information about their
+products to public or at least their require signing a NDA. It's not
+possible to implement a freeware driver for them. However it's possible
+that support for such cards become available in the commercial version
+of this driver (see http://www.4Front-tech.com/oss.html for more info).
+
+There are some common audio chipsets that are not supported yet. For example
+Sierra Aria and IBM Mwave. It's possible that these architectures
+get some support in future but I can't make any promises. Just look
+at the home page (http://www.opensound.com/ossfree/new_cards.html)
+for latest info.
+
+Information about unsupported sound cards and chipsets is welcome as well
+as free copies of sound cards, SDKs and operating systems.
+
+If you have any corrections and/or comments, please contact me.
+
+Hannu Savolainen
+hannu@opensound.com
+
+Personal home page: http://www.compusonic.fi/~hannu
+home page of OSS/Free: http://www.opensound.com/ossfree
+
+home page of commercial OSS
+(Open Sound System) drivers: http://www.opensound.com/oss.html
diff --git a/Documentation/sound/oss/README.modules b/Documentation/sound/oss/README.modules
new file mode 100644
index 0000000..e691d74
--- /dev/null
+++ b/Documentation/sound/oss/README.modules
@@ -0,0 +1,106 @@
+Building a modular sound driver
+================================
+
+ The following information is current as of linux-2.1.85. Check the other
+readme files, especially README.OSS, for information not specific to
+making sound modular.
+
+ First, configure your kernel. This is an idea of what you should be
+setting in the sound section:
+
+<M> Sound card support
+
+<M> 100% Sound Blaster compatibles (SB16/32/64, ESS, Jazz16) support
+
+ I have SoundBlaster. Select your card from the list.
+
+<M> Generic OPL2/OPL3 FM synthesizer support
+<M> FM synthesizer (YM3812/OPL-3) support
+
+ If you don't set these, you will probably find you can play .wav files
+but not .midi. As the help for them says, set them unless you know your
+card does not use one of these chips for FM support.
+
+ Once you are configured, make zlilo, modules, modules_install; reboot.
+Note that it is no longer necessary or possible to configure sound in the
+drivers/sound dir. Now one simply configures and makes one's kernel and
+modules in the usual way.
+
+ Then, add to your /etc/modprobe.conf something like:
+
+alias char-major-14-* sb
+install sb /sbin/modprobe -i sb && /sbin/modprobe adlib_card
+options sb io=0x220 irq=7 dma=1 dma16=5 mpu_io=0x330
+options adlib_card io=0x388 # FM synthesizer
+
+ Alternatively, if you have compiled in kernel level ISAPnP support:
+
+alias char-major-14 sb
+post-install sb /sbin/modprobe "-k" "adlib_card"
+options adlib_card io=0x388
+
+ The effect of this is that the sound driver and all necessary bits and
+pieces autoload on demand, assuming you use kerneld (a sound choice) and
+autoclean when not in use. Also, options for the device drivers are
+set. They will not work without them. Change as appropriate for your card.
+If you are not yet using the very cool kerneld, you will have to "modprobe
+-k sb" yourself to get things going. Eventually things may be fixed so
+that this kludgery is not necessary; for the time being, it seems to work
+well.
+
+ Replace 'sb' with the driver for your card, and give it the right
+options. To find the filename of the driver, look in
+/lib/modules/<kernel-version>/misc. Mine looks like:
+
+adlib_card.o # This is the generic OPLx driver
+opl3.o # The OPL3 driver
+sb.o # <<The SoundBlaster driver. Yours may differ.>>
+sound.o # The sound driver
+uart401.o # Used by sb, maybe other cards
+
+ Whichever card you have, try feeding it the options that would be the
+default if you were making the driver wired, not as modules. You can
+look at function referred to by module_init() for the card to see what
+args are expected.
+
+ Note that at present there is no way to configure the io, irq and other
+parameters for the modular drivers as one does for the wired drivers.. One
+needs to pass the modules the necessary parameters as arguments, either
+with /etc/modprobe.conf or with command-line args to modprobe, e.g.
+
+modprobe sb io=0x220 irq=7 dma=1 dma16=5 mpu_io=0x330
+modprobe adlib_card io=0x388
+
+ recommend using /etc/modprobe.conf.
+
+Persistent DMA Buffers:
+
+The sound modules normally allocate DMA buffers during open() and
+deallocate them during close(). Linux can often have problems allocating
+DMA buffers for ISA cards on machines with more than 16MB RAM. This is
+because ISA DMA buffers must exist below the 16MB boundary and it is quite
+possible that we can't find a large enough free block in this region after
+the machine has been running for any amount of time. The way to avoid this
+problem is to allocate the DMA buffers during module load and deallocate
+them when the module is unloaded. For this to be effective we need to load
+the sound modules right after the kernel boots, either manually or by an
+init script, and keep them around until we shut down. This is a little
+wasteful of RAM, but it guarantees that sound always works.
+
+To make the sound driver use persistent DMA buffers we need to pass the
+sound.o module a "dmabuf=1" command-line argument. This is normally done
+in /etc/modprobe.conf like so:
+
+options sound dmabuf=1
+
+If you have 16MB or less RAM or a PCI sound card, this is wasteful and
+unnecessary. It is possible that machine with 16MB or less RAM will find
+this option useful, but if your machine is so memory-starved that it
+cannot find a 64K block free, you will be wasting even more RAM by keeping
+the sound modules loaded and the DMA buffers allocated when they are not
+needed. The proper solution is to upgrade your RAM. But you do also have
+this improper solution as well. Use it wisely.
+
+ I'm afraid I know nothing about anything but my setup, being more of a
+text-mode guy anyway. If you have options for other cards or other helpful
+hints, send them to me, Jim Bray, jb@as220.org, http://as220.org/jb.
diff --git a/Documentation/sound/oss/README.ymfsb b/Documentation/sound/oss/README.ymfsb
new file mode 100644
index 0000000..af8a7d3
--- /dev/null
+++ b/Documentation/sound/oss/README.ymfsb
@@ -0,0 +1,107 @@
+Legacy audio driver for YMF7xx PCI cards.
+
+
+FIRST OF ALL
+============
+
+ This code references YAMAHA's sample codes and data sheets.
+ I respect and thank for all people they made open the informations
+ about YMF7xx cards.
+
+ And this codes heavily based on Jeff Garzik <jgarzik@pobox.com>'s
+ old VIA 82Cxxx driver (via82cxxx.c). I also respect him.
+
+
+DISCLIMER
+=========
+
+ This driver is currently at early ALPHA stage. It may cause serious
+ damage to your computer when used.
+ PLEASE USE IT AT YOUR OWN RISK.
+
+
+ABOUT THIS DRIVER
+=================
+
+ This code enables you to use your YMF724[A-F], YMF740[A-C], YMF744, YMF754
+ cards. When enabled, your card acts as "SoundBlaster Pro" compatible card.
+ It can only play 22.05kHz / 8bit / Stereo samples, control external MIDI
+ port.
+ If you want to use your card as recent "16-bit" card, you should use
+ Alsa or OSS/Linux driver. Of course you can write native PCI driver for
+ your cards :)
+
+
+USAGE
+=====
+
+ # modprobe ymfsb (options)
+
+
+OPTIONS FOR MODULE
+==================
+
+ io : SB base address (0x220, 0x240, 0x260, 0x280)
+ synth_io : OPL3 base address (0x388, 0x398, 0x3a0, 0x3a8)
+ dma : DMA number (0,1,3)
+ master_volume: AC'97 PCM out Vol (0-100)
+ spdif_out : SPDIF-out flag (0:disable 1:enable)
+
+ These options will change in future...
+
+
+FREQUENCY
+=========
+
+ When playing sounds via this driver, you will hear its pitch is slightly
+ lower than original sounds. Since this driver recognizes your card acts
+ with 21.739kHz sample rates rather than 22.050kHz (I think it must be
+ hardware restriction). So many players become tone deafness.
+ To prevent this, you should express some options to your sound player
+ that specify correct sample frequency. For example, to play your MP3 file
+ correctly with mpg123, specify the frequency like following:
+
+ % mpg123 -r 21739 foo.mp3
+
+
+SPDIF OUT
+=========
+
+ With installing modules with option 'spdif_out=1', you can enjoy your
+ sounds from SPDIF-out of your card (if it had).
+ Its Fs is fixed to 48kHz (It never means the sample frequency become
+ up to 48kHz. All sounds via SPDIF-out also 22kHz samples). So your
+ digital-in capable components has to be able to handle 48kHz Fs.
+
+
+COPYING
+=======
+
+ This program is free software; 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, or (at your option)
+ any later version.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ General Public License for more details.
+
+ 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., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+
+TODO
+====
+ * support for multiple cards
+ (set the different SB_IO,MPU_IO,OPL_IO for each cards)
+
+ * support for OPL (dmfm) : There will be no requirements... :-<
+
+
+AUTHOR
+======
+
+ Daisuke Nagano <breeze.nagano@nifty.ne.jp>
+
diff --git a/Documentation/sound/oss/SoundPro b/Documentation/sound/oss/SoundPro
new file mode 100644
index 0000000..9d4db1f
--- /dev/null
+++ b/Documentation/sound/oss/SoundPro
@@ -0,0 +1,105 @@
+Documentation for the SoundPro CMI8330 extensions in the WSS driver (ad1848.o)
+------------------------------------------------------------------------------
+
+( Be sure to read Documentation/sound/oss/CMI8330 too )
+
+Ion Badulescu, ionut@cs.columbia.edu
+February 24, 1999
+
+(derived from the OPL3-SA2 documentation by Scott Murray)
+
+The SoundPro CMI8330 (ISA) is a chip usually found on some Taiwanese
+motherboards. The official name in the documentation is CMI8330, SoundPro
+is the nickname and the big inscription on the chip itself.
+
+The chip emulates a WSS as well as a SB16, but it has certain differences
+in the mixer section which require separate support. It also emulates an
+MPU401 and an OPL3 synthesizer, so you probably want to enable support
+for these, too.
+
+The chip identifies itself as an AD1848, but its mixer is significantly
+more advanced than the original AD1848 one. If your system works with
+either WSS or SB16 and you are having problems with some mixer controls
+(no CD audio, no line-in, etc), you might want to give this driver a try.
+Detection should work, but it hasn't been widely tested, so it might still
+mis-identify the chip. You can still force soundpro=1 in the modprobe
+parameters for ad1848. Please let me know if it happens to you, so I can
+adjust the detection routine.
+
+The chip is capable of doing full-duplex, but since the driver sees it as an
+AD1848, it cannot take advantage of this. Moreover, the full-duplex mode is
+not achievable through the WSS interface, b/c it needs a dma16 line which is
+assigned only to the SB16 subdevice (with isapnp). Windows documentation
+says the user must use WSS Playback and SB16 Recording for full-duplex, so
+it might be possible to do the same thing under Linux. You can try loading
+up both ad1848 and sb then use one for playback and the other for
+recording. I don't know if this works, b/c I haven't tested it. Anyway, if
+you try it, be very careful: the SB16 mixer *mostly* works, but certain
+settings can have unexpected effects. Use the WSS mixer for best results.
+
+There is also a PCI SoundPro chip. I have not seen this chip, so I have
+no idea if the driver will work with it. I suspect it won't.
+
+As with PnP cards, some configuration is required. There are two ways
+of doing this. The most common is to use the isapnptools package to
+initialize the card, and use the kernel module form of the sound
+subsystem and sound drivers. Alternatively, some BIOS's allow manual
+configuration of installed PnP devices in a BIOS menu, which should
+allow using the non-modular sound drivers, i.e. built into the kernel.
+Since in this latter case you cannot use module parameters, you will
+have to enable support for the SoundPro at compile time.
+
+The IRQ and DMA values can be any that are considered acceptable for a
+WSS. Assuming you've got isapnp all happy, then you should be able to
+do something like the following (which *must* match the isapnp/BIOS
+configuration):
+
+modprobe ad1848 io=0x530 irq=11 dma=0 soundpro=1
+-and maybe-
+modprobe sb io=0x220 irq=5 dma=1 dma16=5
+
+-then-
+modprobe mpu401 io=0x330 irq=9
+modprobe opl3 io=0x388
+
+If all goes well and you see no error messages, you should be able to
+start using the sound capabilities of your system. If you get an
+error message while trying to insert the module(s), then make
+sure that the values of the various arguments match what you specified
+in your isapnp configuration file, and that there is no conflict with
+another device for an I/O port or interrupt. Checking the contents of
+/proc/ioports and /proc/interrupts can be useful to see if you're
+butting heads with another device.
+
+If you do not see the chipset version message, and none of the other
+messages present in the system log are helpful, try adding 'debug=1'
+to the ad1848 parameters, email me the syslog results and I'll do
+my best to help.
+
+Lastly, if you're using modules and want to set up automatic module
+loading with kmod, the kernel module loader, here is the section I
+currently use in my conf.modules file:
+
+# Sound
+post-install sound modprobe -k ad1848; modprobe -k mpu401; modprobe -k opl3
+options ad1848 io=0x530 irq=11 dma=0
+options sb io=0x220 irq=5 dma=1 dma16=5
+options mpu401 io=0x330 irq=9
+options opl3 io=0x388
+
+The above ensures that ad1848 will be loaded whenever the sound system
+is being used.
+
+Good luck.
+
+Ion
+
+NOT REALLY TESTED:
+- recording
+- recording device selection
+- full-duplex
+
+TODO:
+- implement mixer support for surround, loud, digital CD switches.
+- come up with a scheme which allows recording volumes for each subdevice.
+This is a major OSS API change.
diff --git a/Documentation/sound/oss/Soundblaster b/Documentation/sound/oss/Soundblaster
new file mode 100644
index 0000000..b288d46
--- /dev/null
+++ b/Documentation/sound/oss/Soundblaster
@@ -0,0 +1,53 @@
+modprobe sound
+insmod uart401
+insmod sb ...
+
+This loads the driver for the Sound Blaster and assorted clones. Cards that
+are covered by other drivers should not be using this driver.
+
+The Sound Blaster module takes the following arguments
+
+io I/O address of the Sound Blaster chip (0x220,0x240,0x260,0x280)
+irq IRQ of the Sound Blaster chip (5,7,9,10)
+dma 8-bit DMA channel for the Sound Blaster (0,1,3)
+dma16 16-bit DMA channel for SB16 and equivalent cards (5,6,7)
+mpu_io I/O for MPU chip if present (0x300,0x330)
+
+sm_games=1 Set if you have a Logitech soundman games
+acer=1 Set this to detect cards in some ACER notebooks
+mwave_bug=1 Set if you are trying to use this driver with mwave (see on)
+type Use this to specify a specific card type
+
+The following arguments are taken if ISAPnP support is compiled in
+
+isapnp=0 Set this to disable ISAPnP detection (use io=0xXXX etc. above)
+multiple=0 Set to disable detection of multiple Soundblaster cards.
+ Consider it a bug if this option is needed, and send in a
+ report.
+pnplegacy=1 Set this to be able to use a PnP card(s) along with a single
+ non-PnP (legacy) card. Above options for io, irq, etc. are
+ needed, and will apply only to the legacy card.
+reverse=1 Reverses the order of the search in the PnP table.
+uart401=1 Set to enable detection of mpu devices on some clones.
+isapnpjump=n Jumps to slot n in the driver's PnP table. Use the source,
+ Luke.
+
+You may well want to load the opl3 driver for synth music on most SB and
+clone SB devices
+
+insmod opl3 io=0x388
+
+Using Mwave
+
+To make this driver work with Mwave you must set mwave_bug. You also need
+to warm boot from DOS/Windows with the required firmware loaded under this
+OS. IBM are being difficult about documenting how to load this firmware.
+
+Avance Logic ALS007
+
+This card is supported; see the separate file ALS007 for full details.
+
+Avance Logic ALS100
+
+This card is supported; setup should be as for a standard Sound Blaster 16.
+The driver will identify the audio device as a "Sound Blaster 16 (ALS-100)".
diff --git a/Documentation/sound/oss/Tropez+ b/Documentation/sound/oss/Tropez+
new file mode 100644
index 0000000..b93a6b7
--- /dev/null
+++ b/Documentation/sound/oss/Tropez+
@@ -0,0 +1,26 @@
+From: Paul Barton-Davis <pbd@op.net>
+
+Here is the configuration I use with a Tropez+ and my modular
+driver:
+
+ alias char-major-14 wavefront
+ alias synth0 wavefront
+ alias mixer0 cs4232
+ alias audio0 cs4232
+ pre-install wavefront modprobe "-k" "cs4232"
+ post-install wavefront modprobe "-k" "opl3"
+ options wavefront io=0x200 irq=9
+ options cs4232 synthirq=9 synthio=0x200 io=0x530 irq=5 dma=1 dma2=0
+ options opl3 io=0x388
+
+Things to note:
+
+ the wavefront options "io" and "irq" ***MUST*** match the "synthio"
+ and "synthirq" cs4232 options.
+
+ you can do without the opl3 module if you don't
+ want to use the OPL/[34] synth on the soundcard
+
+ the opl3 io parameter is conventionally not adjustable.
+
+Please see drivers/sound/README.wavefront for more details.
diff --git a/Documentation/sound/oss/VIBRA16 b/Documentation/sound/oss/VIBRA16
new file mode 100644
index 0000000..68a5a46
--- /dev/null
+++ b/Documentation/sound/oss/VIBRA16
@@ -0,0 +1,80 @@
+Sound Blaster 16X Vibra addendum
+--------------------------------
+by Marius Ilioaea <mariusi@protv.ro>
+ Stefan Laudat <stefan@asit.ro>
+
+Sat Mar 6 23:55:27 EET 1999
+
+ Hello again,
+
+ Playing with a SB Vibra 16x soundcard we found it very difficult
+to setup because the kernel reported a lot of DMA errors and wouldn't
+simply play any sound.
+ A good starting point is that the vibra16x chip full-duplex facility
+is neither still exploited by the sb driver found in the linux kernel
+(tried it with a 2.2.2-ac7), nor in the commercial OSS package (it reports
+it as half-duplex soundcard). Oh, I almost forgot, the RedHat sndconfig
+failed detecting it ;)
+ So, the big problem still remains, because the sb module wants a
+8-bit and a 16-bit dma, which we could not allocate for vibra... it supports
+only two 8-bit dma channels, the second one will be passed to the module
+as a 16 bit channel, the kernel will yield about that but everything will
+be okay, trust us.
+ The only inconvenient you may find is that you will have
+some sound playing jitters if you have HDD dma support enabled - but this
+will happen with almost all soundcards...
+
+ A fully working isapnp.conf is just here:
+
+<snip here>
+
+(READPORT 0x0203)
+(ISOLATE PRESERVE)
+(IDENTIFY *)
+(VERBOSITY 2)
+(CONFLICT (IO FATAL)(IRQ FATAL)(DMA FATAL)(MEM FATAL)) # or WARNING
+# SB 16 and OPL3 devices
+(CONFIGURE CTL00f0/-1 (LD 0
+(INT 0 (IRQ 5 (MODE +E)))
+(DMA 0 (CHANNEL 1))
+(DMA 1 (CHANNEL 3))
+(IO 0 (SIZE 16) (BASE 0x0220))
+(IO 2 (SIZE 4) (BASE 0x0388))
+(NAME "CTL00f0/-1[0]{Audio }")
+(ACT Y)
+))
+
+# Joystick device - only if you need it :-/
+
+(CONFIGURE CTL00f0/-1 (LD 1
+(IO 0 (SIZE 1) (BASE 0x0200))
+(NAME "CTL00f0/-1[1]{Game }")
+(ACT Y)
+))
+(WAITFORKEY)
+
+<end of snipping>
+
+ So, after a good kernel modules compilation and a 'depmod -a kernel_ver'
+you may want to:
+
+modprobe sb io=0x220 irq=5 dma=1 dma16=3
+
+ Or, take the hard way:
+
+modprobe soundcore
+modprobe sound
+modprobe uart401
+modprobe sb io=0x220 irq=5 dma=1 dma16=3
+# do you need MIDI?
+modprobe opl3=0x388
+
+ Just in case, the kernel sound support should be:
+
+CONFIG_SOUND=m
+CONFIG_SOUND_OSS=m
+CONFIG_SOUND_SB=m
+
+ Enjoy your new noisy Linux box! ;)
+
+
diff --git a/Documentation/sound/oss/WaveArtist b/Documentation/sound/oss/WaveArtist
new file mode 100644
index 0000000..f4f3407
--- /dev/null
+++ b/Documentation/sound/oss/WaveArtist
@@ -0,0 +1,170 @@
+
+ (the following is from the armlinux CVS)
+
+ WaveArtist mixer and volume levels can be accessed via these commands:
+
+ nn30 read registers nn, where nn = 00 - 09 for mixer settings
+ 0a - 13 for channel volumes
+ mm31 write the volume setting in pairs, where mm = (nn - 10) / 2
+ rr32 write the mixer settings in pairs, where rr = nn/2
+ xx33 reset all settings to default
+ 0y34 select mono source, y=0 = left, y=1 = right
+
+ bits
+ nn 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 00 | 0 | 0 0 1 1 | left line mixer gain | left aux1 mixer gain |lmute|
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 01 | 0 | 0 1 0 1 | left aux2 mixer gain | right 2 left mic gain |mmute|
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 02 | 0 | 0 1 1 1 | left mic mixer gain | left mic | left mixer gain |dith |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 03 | 0 | 1 0 0 1 | left mixer input select |lrfg | left ADC gain |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 04 | 0 | 1 0 1 1 | right line mixer gain | right aux1 mixer gain |rmute|
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 05 | 0 | 1 1 0 1 | right aux2 mixer gain | left 2 right mic gain |test |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 06 | 0 | 1 1 1 1 | right mic mixer gain | right mic |right mixer gain |rbyps|
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 07 | 1 | 0 0 0 1 | right mixer select |rrfg | right ADC gain |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 08 | 1 | 0 0 1 1 | mono mixer gain |right ADC mux sel|left ADC mux sel |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 09 | 1 | 0 1 0 1 |loopb|left linout|loop|ADCch|TxFch|OffCD|test |loopb|loopb|osamp|
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 0a | 0 | left PCM channel volume |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 0b | 0 | right PCM channel volume |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 0c | 0 | left FM channel volume |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 0d | 0 | right FM channel volume |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 0e | 0 | left wavetable channel volume |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 0f | 0 | right wavetable channel volume |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 10 | 0 | left PCM expansion channel volume |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 11 | 0 | right PCM expansion channel volume |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 12 | 0 | left FM expansion channel volume |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+ 13 | 0 | right FM expansion channel volume |
+----+---+------------+-----+-----+-----+----+-----+-----+-----+-----+-----+-----+-----+
+
+ lmute: left mute
+ mmute: mono mute
+ dith: dithds
+ lrfg:
+ rmute: right mute
+ rbyps: right bypass
+ rrfg:
+ ADCch:
+ TxFch:
+ OffCD:
+ osamp:
+
+ And the following diagram is derived from the description in the CVS archive:
+
+ MIC L (mouthpiece)
+ +------+
+ -->PreAmp>-\
+ +--^---+ |
+ | |
+ r2b4-5 | +--------+
+ /----*-------------------------------->5 |
+ | | |
+ | /----------------------------------->4 |
+ | | | |
+ | | /--------------------------------->3 1of5 | +---+
+ | | | | mux >-->AMP>--> ADC L
+ | | | /------------------------------->2 | +-^-+
+ | | | | | | |
+ Line | | | | +----+ +------+ +---+ /---->1 | r3b3-0
+ ------------*->mute>--> Gain >--> | | | |
+ L | | | +----+ +------+ | | | *->0 |
+ | | | | | | +---^----+
+ Aux2 | | | +----+ +------+ | | | |
+ ----------*--->mute>--> Gain >--> M | | r8b0-2
+ L | | +----+ +------+ | | |
+ | | | | \------\
+ Aux1 | | +----+ +------+ | | |
+ --------*----->mute>--> Gain >--> I | |
+ L | +----+ +------+ | | |
+ | | | |
+ | +----+ +------+ | | +---+ |
+ *------->mute>--> Gain >--> X >-->AMP>--*
+ | +----+ +------+ | | +-^-+ |
+ | | | | |
+ | +----+ +------+ | | r2b1-3 |
+ | /----->mute>--> Gain >--> E | |
+ | | +----+ +------+ | | |
+ | | | | |
+ | | +----+ +------+ | | |
+ | | /--->mute>--> Gain >--> R | |
+ | | | +----+ +------+ | | |
+ | | | | | | r9b8-9
+ | | | +----+ +------+ | | | |
+ | | | /->mute>--> Gain >--> | | +---v---+
+ | | | | +----+ +------+ +---+ /-*->0 |
+ DAC | | | | | | |
+ ------------*----------------------------------->? | +----+
+ L | | | | | Mux >-->mute>--> L output
+ | | | | /->? | +--^-+
+ | | | | | | | |
+ | | | /--------->? | r0b0
+ | | | | | | +-------+
+ | | | | | |
+ Mono | | | | | | +-------+
+ ----------* | \---> | +----+
+ | | | | | | Mix >-->mute>--> Mono output
+ | | | | *-> | +--^-+
+ | | | | | +-------+ |
+ | | | | | r1b0
+ DAC | | | | | +-------+
+ ------------*-------------------------*--------->1 | +----+
+ R | | | | | | Mux >-->mute>--> R output
+ | | | | +----+ +------+ +---+ *->0 | +--^-+
+ | | | \->mute>--> Gain >--> | | +---^---+ |
+ | | | +----+ +------+ | | | | r5b0
+ | | | | | | r6b0
+ | | | +----+ +------+ | | |
+ | | \--->mute>--> Gain >--> M | |
+ | | +----+ +------+ | | |
+ | | | | |
+ | | +----+ +------+ | | |
+ | *----->mute>--> Gain >--> I | |
+ | | +----+ +------+ | | |
+ | | | | |
+ | | +----+ +------+ | | +---+ |
+ \------->mute>--> Gain >--> X >-->AMP>--*
+ | +----+ +------+ | | +-^-+ |
+ /--/ | | | |
+ Aux1 | +----+ +------+ | | r6b1-3 |
+ -------*------>mute>--> Gain >--> E | |
+ R | | +----+ +------+ | | |
+ | | | | |
+ Aux2 | | +----+ +------+ | | /------/
+ ---------*---->mute>--> Gain >--> R | |
+ R | | | +----+ +------+ | | |
+ | | | | | | +--------+
+ Line | | | +----+ +------+ | | | *->0 |
+ -----------*-->mute>--> Gain >--> | | | |
+ R | | | | +----+ +------+ +---+ \---->1 |
+ | | | | | |
+ | | | \-------------------------------->2 | +---+
+ | | | | Mux >-->AMP>--> ADC R
+ | | \---------------------------------->3 | +-^-+
+ | | | | |
+ | \------------------------------------>4 | r7b3-0
+ | | |
+ \-----*-------------------------------->5 |
+ | +---^----+
+ r6b4-5 | |
+ | | r8b3-5
+ +--v---+ |
+ -->PreAmp>-/
+ +------+
+ MIC R (electret mic)
diff --git a/Documentation/sound/oss/btaudio b/Documentation/sound/oss/btaudio
new file mode 100644
index 0000000..1a693e6
--- /dev/null
+++ b/Documentation/sound/oss/btaudio
@@ -0,0 +1,92 @@
+
+Intro
+=====
+
+people start bugging me about this with questions, looks like I
+should write up some documentation for this beast. That way I
+don't have to answer that much mails I hope. Yes, I'm lazy...
+
+
+You might have noticed that the bt878 grabber cards have actually
+_two_ PCI functions:
+
+$ lspci
+[ ... ]
+00:0a.0 Multimedia video 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. btaudio is a driver for the second function. It's a sound
+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...
+
+
+Driver Status
+=============
+
+Still somewhat experimental. The driver should work stable, i.e. it
+should'nt crash your box. It might not work as expected, have bugs,
+not being fully OSS API compilant, ...
+
+Latest versions are available from http://bytesex.org/bttv/, the
+driver is in the bttv tarball. Kernel patches might be available too,
+have a look at http://bytesex.org/bttv/listing.html.
+
+The chip knows two different modes. btaudio registers two dsp
+devices, one for each mode. They can not be used at the same time.
+
+
+Digital audio mode
+==================
+
+The chip gives you 16 bit stereo sound. The sample rate depends on
+the external source which feeds the bt878 with digital sound via I2S
+interface. There is a insmod option (rate) to tell the driver which
+sample rate the hardware uses (32000 is the default).
+
+One possible source for digital sound is the msp34xx audio processor
+chip which provides digital sound via I2S with 32 kHz sample rate. My
+Hauppauge board works this way.
+
+The Osprey-200 reportly gives you digital sound with 44100 Hz sample
+rate. It is also possible that you get no sound at all.
+
+
+analog mode (A/D)
+=================
+
+You can tell the driver to use this mode with the insmod option "analog=1".
+The chip has three analog inputs. Consequently you'll get a mixer device
+to control these.
+
+The analog mode supports mono only. Both 8 + 16 bit. Both are _signed_
+int, which is uncommon for the 8 bit case. Sample rate range is 119 kHz
+to 448 kHz. Yes, the number of digits is correct. The driver supports
+downsampling by powers of two, so you can ask for more usual sample rates
+like 44 kHz too.
+
+With my Hauppauge I get noisy sound on the second input (mapped to line2
+by the mixer device). Others get a useable signal on line1.
+
+
+some examples
+=============
+
+* read audio data from btaudio (dsp2), send to es1730 (dsp,dsp1):
+ $ sox -w -r 32000 -t ossdsp /dev/dsp2 -t ossdsp /dev/dsp
+
+* read audio data from btaudio, send to esound daemon (which might be
+ running on another host):
+ $ sox -c 2 -w -r 32000 -t ossdsp /dev/dsp2 -t sw - | esdcat -r 32000
+ $ sox -c 1 -w -r 32000 -t ossdsp /dev/dsp2 -t sw - | esdcat -m -r 32000
+
+
+Have fun,
+
+ Gerd
+
+--
+Gerd Knorr <kraxel@bytesex.org>
diff --git a/Documentation/sound/oss/mwave b/Documentation/sound/oss/mwave
new file mode 100644
index 0000000..5fbcb16
--- /dev/null
+++ b/Documentation/sound/oss/mwave
@@ -0,0 +1,185 @@
+ How to try to survive an IBM Mwave under Linux SB drivers
+
+
++ IBM have now released documentation of sorts and Torsten is busy
+ trying to make the Mwave work. This is not however a trivial task.
+
+----------------------------------------------------------------------------
+
+OK, first thing - the IRQ problem IS a problem, whether the test is bypassed or
+not. It is NOT a Linux problem, but an MWAVE problem that is fixed with the
+latest MWAVE patches. So, in other words, don't bypass the test for MWAVES!
+
+I have Windows 95 on /dev/hda1, swap on /dev/hda2, and Red Hat 5 on /dev/hda3.
+
+The steps, then:
+
+ Boot to Linux.
+ Mount Windows 95 file system (assume mount point = /dos95).
+ mkdir /dos95/linux
+ mkdir /dos95/linux/boot
+ mkdir /dos95/linux/boot/parms
+
+ Copy the kernel, any initrd image, and loadlin to /dos95/linux/boot/.
+
+ Reboot to Windows 95.
+
+ Edit C:/msdos.sys and add or change the following:
+
+ Logo=0
+ BootGUI=0
+
+ Note that msdos.sys is a text file but it needs to be made 'unhidden',
+ readable and writable before it can be edited. This can be done with
+ DOS' "attrib" command.
+
+ Edit config.sys to have multiple config menus. I have one for windows 95 and
+ five for Linux, like this:
+------------
+[menu]
+menuitem=W95, Windows 95
+menuitem=LINTP, Linux - ThinkPad
+menuitem=LINTP3, Linux - ThinkPad Console
+menuitem=LINDOC, Linux - Docked
+menuitem=LINDOC3, Linux - Docked Console
+menuitem=LIN1, Linux - Single User Mode
+REM menudefault=W95,10
+
+[W95]
+
+[LINTP]
+
+[LINDOC]
+
+[LINTP3]
+
+[LINDOC3]
+
+[LIN1]
+
+[COMMON]
+FILES=30
+REM Please read README.TXT in C:\MWW subdirectory before changing the DOS= statement.
+DOS=HIGH,UMB
+DEVICE=C:\MWW\MANAGER\MWD50430.EXE
+SHELL=c:\command.com /e:2048
+-------------------
+
+The important things are the SHELL and DEVICE statements.
+
+ Then change autoexec.bat. Basically everything in there originally should be
+ done ONLY when Windows 95 is booted. Then you add new things specifically
+ for Linux. Mine is as follows
+
+---------------
+@ECHO OFF
+if "%CONFIG%" == "W95" goto W95
+
+REM
+REM Linux stuff
+REM
+SET MWPATH=C:\MWW\DLL;C:\MWW\MWGAMES;C:\MWW\DSP
+SET BLASTER=A220 I5 D1
+SET MWROOT=C:\MWW
+SET LIBPATH=C:\MWW\DLL
+SET PATH=C:\WINDOWS;C:\MWW\DLL;
+CALL MWAVE START NOSHOW
+c:\linux\boot\loadlin.exe @c:\linux\boot\parms\%CONFIG%.par
+
+:W95
+REM
+REM Windows 95 stuff
+REM
+c:\toolkit\guard
+SET MSINPUT=C:\MSINPUT
+SET MWPATH=C:\MWW\DLL;C:\MWW\MWGAMES;C:\MWW\DSP
+REM The following is used by DOS games to recognize Sound Blaster hardware.
+REM If hardware settings are changed, please change this line as well.
+REM See the Mwave README file for instructions.
+SET BLASTER=A220 I5 D1
+SET MWROOT=C:\MWW
+SET LIBPATH=C:\MWW\DLL
+SET PATH=C:\WINDOWS;C:\WINDOWS\COMMAND;E:\ORAWIN95\BIN;f:\msdev\bin;e:\v30\bin.dbg;v:\devt\v30\bin;c:\JavaSDK\Bin;C:\MWW\DLL;
+SET INCLUDE=f:\MSDEV\INCLUDE;F:\MSDEV\MFC\INCLUDE
+SET LIB=F:\MSDEV\LIB;F:\MSDEV\MFC\LIB
+win
+
+------------------------
+
+Now build a file in c:\linux\boot\parms for each Linux config that you have.
+
+For example, my LINDOC3 config is for a docked Thinkpad at runlevel 3 with no
+initrd image, and has a parameter file named LINDOC3.PAR in c:\linux\boot\parms:
+
+-----------------------
+# LOADLIN @param_file image=other_image root=/dev/other
+#
+# Linux Console in docking station
+#
+c:\linux\boot\zImage.krn # First value must be filename of Linux kernel.
+root=/dev/hda3 # device which gets mounted as root FS
+ro # Other kernel arguments go here.
+apm=off
+doc=yes
+3
+-----------------------
+
+The doc=yes parameter is an environment variable used by my init scripts, not
+a kernel argument.
+
+However, the apm=off parameter IS a kernel argument! APM, at least in my setup,
+causes the kernel to crash when loaded via loadlin (but NOT when loaded via
+LILO). The APM stuff COULD be forced out of the kernel via the kernel compile
+options. Instead, I got an unofficial patch to the APM drivers that allows them
+to be dynamically deactivated via kernel arguments. Whatever you chose to
+document, APM, it seems, MUST be off for setups like mine.
+
+Now make sure C:\MWW\MWCONFIG.REF looks like this:
+
+----------------------
+[NativeDOS]
+Default=SB1.5
+SBInputSource=CD
+SYNTH=FM
+QSound=OFF
+Reverb=OFF
+Chorus=OFF
+ReverbDepth=5
+ChorusDepth=5
+SBInputVolume=5
+SBMainVolume=10
+SBWaveVolume=10
+SBSynthVolume=10
+WaveTableVolume=10
+AudioPowerDriver=ON
+
+[FastCFG]
+Show=No
+HideOption=Off
+-----------------------------
+
+OR the Default= line COULD be
+
+Default=SBPRO
+
+Reboot to Windows 95 and choose Linux. When booted, use sndconfig to configure
+the sound modules and voilĂ  - ThinkPad sound with Linux.
+
+Now the gotchas - you can either have CD sound OR Mixers but not both. That's a
+problem with the SB1.5 (CD sound) or SBPRO (Mixers) settings. No one knows why
+this is!
+
+For some reason MPEG3 files, when played through mpg123, sound like they
+are playing at 1/8th speed - not very useful! If you have ANY insight
+on why this second thing might be happening, I would be grateful.
+
+===========================================================
+ _/ _/_/_/_/
+ _/_/ _/_/ _/
+ _/ _/_/ _/_/_/_/ Martin John Bartlett
+ _/ _/ _/ _/ (martin@nitram.demon.co.uk)
+_/ _/_/_/_/
+ _/
+_/ _/
+ _/_/
+===========================================================
diff --git a/Documentation/sound/oss/ultrasound b/Documentation/sound/oss/ultrasound
new file mode 100644
index 0000000..eed331c
--- /dev/null
+++ b/Documentation/sound/oss/ultrasound
@@ -0,0 +1,30 @@
+modprobe sound
+insmod ad1848
+insmod gus io=* irq=* dma=* ...
+
+This loads the driver for the Gravis Ultrasound family of sound cards.
+
+The gus module takes the following arguments
+
+io I/O address of the Ultrasound card (eg. io=0x220)
+irq IRQ of the Sound Blaster card
+dma DMA channel for the Sound Blaster
+dma16 2nd DMA channel, only needed for full duplex operation
+type 1 for PnP card
+gus16 1 for using 16 bit sampling daughter board
+no_wave_dma Set to disable DMA usage for wavetable (see note)
+db16 ???
+
+
+no_wave_dma option
+
+This option defaults to a value of 0, which allows the Ultrasound wavetable
+DSP to use DMA for playback and downloading samples. This is the same
+as the old behaviour. If set to 1, no DMA is needed for downloading samples,
+and allows owners of a GUS MAX to make use of simultaneous digital audio
+(/dev/dsp), MIDI, and wavetable playback.
+
+
+If you have problems in recording with GUS MAX, you could try to use
+just one 8 bit DMA channel. Recording will not work with one DMA
+channel if it's a 16 bit one.
diff --git a/Documentation/sound/oss/vwsnd b/Documentation/sound/oss/vwsnd
new file mode 100644
index 0000000..4c6cbdb
--- /dev/null
+++ b/Documentation/sound/oss/vwsnd
@@ -0,0 +1,293 @@
+vwsnd - Sound driver for the Silicon Graphics 320 and 540 Visual
+Workstations' onboard audio.
+
+Copyright 1999 Silicon Graphics, Inc. All rights reserved.
+
+
+At the time of this writing, March 1999, there are two models of
+Visual Workstation, the 320 and the 540. This document only describes
+those models. Future Visual Workstation models may have different
+sound capabilities, and this driver will probably not work on those
+boxes.
+
+The Visual Workstation has an Analog Devices AD1843 "SoundComm" audio
+codec chip. The AD1843 is accessed through the Cobalt I/O ASIC, also
+known as Lithium. This driver programs both chips.
+
+==============================================================================
+QUICK CONFIGURATION
+
+ # insmod soundcore
+ # insmod vwsnd
+
+==============================================================================
+I/O CONNECTIONS
+
+On the Visual Workstation, only three of the AD1843 inputs are hooked
+up. The analog line in jacks are connected to the AD1843's AUX1
+input. The CD audio lines are connected to the AD1843's AUX2 input.
+The microphone jack is connected to the AD1843's MIC input. The mic
+jack is mono, but the signal is delivered to both the left and right
+MIC inputs. You can record in stereo from the mic input, but you will
+get the same signal on both channels (within the limits of A/D
+accuracy). Full scale on the Line input is +/- 2.0 V. Full scale on
+the MIC input is 20 dB less, or +/- 0.2 V.
+
+The AD1843's LOUT1 outputs are connected to the Line Out jacks. The
+AD1843's HPOUT outputs are connected to the speaker/headphone jack.
+LOUT2 is not connected. Line out's maximum level is +/- 2.0 V peak to
+peak. The speaker/headphone out's maximum is +/- 4.0 V peak to peak.
+
+The AD1843's PCM input channel and one of its output channels (DAC1)
+are connected to Lithium. The other output channel (DAC2) is not
+connected.
+
+==============================================================================
+CAPABILITIES
+
+The AD1843 has PCM input and output (Pulse Code Modulation, also known
+as wavetable). PCM input and output can be mono or stereo in any of
+four formats. The formats are 16 bit signed and 8 bit unsigned,
+u-Law, and A-Law format. Any sample rate from 4 KHz to 49 KHz is
+available, in 1 Hz increments.
+
+The AD1843 includes an analog mixer that can mix all three input
+signals (line, mic and CD) into the analog outputs. The mixer has a
+separate gain control and mute switch for each input.
+
+There are two outputs, line out and speaker/headphone out. They
+always produce the same signal, and the speaker always has 3 dB more
+gain than the line out. The speaker/headphone output can be muted,
+but this driver does not export that function.
+
+The hardware can sync audio to the video clock, but this driver does
+not have a way to specify syncing to video.
+
+==============================================================================
+PROGRAMMING
+
+This section explains the API supported by the driver. Also see the
+Open Sound Programming Guide at http://www.opensound.com/pguide/ .
+This section assumes familiarity with that document.
+
+The driver has two interfaces, an I/O interface and a mixer interface.
+There is no MIDI or sequencer capability.
+
+==============================================================================
+PROGRAMMING PCM I/O
+
+The I/O interface is usually accessed as /dev/audio or /dev/dsp.
+Using the standard Open Sound System (OSS) ioctl calls, the sample
+rate, number of channels, and sample format may be set within the
+limitations described above. The driver supports triggering. It also
+supports getting the input and output pointers with one-sample
+accuracy.
+
+The SNDCTL_DSP_GETCAP ioctl returns these capabilities.
+
+ DSP_CAP_DUPLEX - driver supports full duplex.
+
+ DSP_CAP_TRIGGER - driver supports triggering.
+
+ DSP_CAP_REALTIME - values returned by SNDCTL_DSP_GETIPTR
+ and SNDCTL_DSP_GETOPTR are accurate to a few samples.
+
+Memory mapping (mmap) is not implemented.
+
+The driver permits subdivided fragment sizes from 64 to 4096 bytes.
+The number of fragments can be anything from 3 fragments to however
+many fragments fit into 124 kilobytes. It is up to the user to
+determine how few/small fragments can be used without introducing
+glitches with a given workload. Linux is not realtime, so we can't
+promise anything. (sigh...)
+
+When this driver is switched into or out of mu-Law or A-Law mode on
+output, it may produce an audible click. This is unavoidable. To
+prevent clicking, use signed 16-bit mode instead, and convert from
+mu-Law or A-Law format in software.
+
+==============================================================================
+PROGRAMMING THE MIXER INTERFACE
+
+The mixer interface is usually accessed as /dev/mixer. It is accessed
+through ioctls. The mixer allows the application to control gain or
+mute several audio signal paths, and also allows selection of the
+recording source.
+
+Each of the constants described here can be read using the
+MIXER_READ(SOUND_MIXER_xxx) ioctl. Those that are not read-only can
+also be written using the MIXER_WRITE(SOUND_MIXER_xxx) ioctl. In most
+cases, <sys/soundcard.h> defines constants SOUND_MIXER_READ_xxx and
+SOUND_MIXER_WRITE_xxx which work just as well.
+
+SOUND_MIXER_CAPS Read-only
+
+This is a mask of optional driver capabilities that are implemented.
+This driver's only capability is SOUND_CAP_EXCL_INPUT, which means
+that only one recording source can be active at a time.
+
+SOUND_MIXER_DEVMASK Read-only
+
+This is a mask of the sound channels. This driver's channels are PCM,
+LINE, MIC, CD, and RECLEV.
+
+SOUND_MIXER_STEREODEVS Read-only
+
+This is a mask of which sound channels are capable of stereo. All
+channels are capable of stereo. (But see caveat on MIC input in I/O
+CONNECTIONS section above).
+
+SOUND_MIXER_OUTMASK Read-only
+
+This is a mask of channels that route inputs through to outputs.
+Those are LINE, MIC, and CD.
+
+SOUND_MIXER_RECMASK Read-only
+
+This is a mask of channels that can be recording sources. Those are
+PCM, LINE, MIC, CD.
+
+SOUND_MIXER_PCM Default: 0x5757 (0 dB)
+
+This is the gain control for PCM output. The left and right channel
+gain are controlled independently. This gain control has 64 levels,
+which range from -82.5 dB to +12.0 dB in 1.5 dB steps. Those 64
+levels are mapped onto 100 levels at the ioctl, see below.
+
+SOUND_MIXER_LINE Default: 0x4a4a (0 dB)
+
+This is the gain control for mixing the Line In source into the
+outputs. The left and right channel gain are controlled
+independently. This gain control has 32 levels, which range from
+-34.5 dB to +12.0 dB in 1.5 dB steps. Those 32 levels are mapped onto
+100 levels at the ioctl, see below.
+
+SOUND_MIXER_MIC Default: 0x4a4a (0 dB)
+
+This is the gain control for mixing the MIC source into the outputs.
+The left and right channel gain are controlled independently. This
+gain control has 32 levels, which range from -34.5 dB to +12.0 dB in
+1.5 dB steps. Those 32 levels are mapped onto 100 levels at the
+ioctl, see below.
+
+SOUND_MIXER_CD Default: 0x4a4a (0 dB)
+
+This is the gain control for mixing the CD audio source into the
+outputs. The left and right channel gain are controlled
+independently. This gain control has 32 levels, which range from
+-34.5 dB to +12.0 dB in 1.5 dB steps. Those 32 levels are mapped onto
+100 levels at the ioctl, see below.
+
+SOUND_MIXER_RECLEV Default: 0 (0 dB)
+
+This is the gain control for PCM input (RECording LEVel). The left
+and right channel gain are controlled independently. This gain
+control has 16 levels, which range from 0 dB to +22.5 dB in 1.5 dB
+steps. Those 16 levels are mapped onto 100 levels at the ioctl, see
+below.
+
+SOUND_MIXER_RECSRC Default: SOUND_MASK_LINE
+
+This is a mask of currently selected PCM input sources (RECording
+SouRCes). Because the AD1843 can only have a single recording source
+at a time, only one bit at a time can be set in this mask. The
+allowable values are SOUND_MASK_PCM, SOUND_MASK_LINE, SOUND_MASK_MIC,
+or SOUND_MASK_CD. Selecting SOUND_MASK_PCM sets up internal
+resampling which is useful for loopback testing and for hardware
+sample rate conversion. But software sample rate conversion is
+probably faster, so I don't know how useful that is.
+
+SOUND_MIXER_OUTSRC DEFAULT: SOUND_MASK_LINE|SOUND_MASK_MIC|SOUND_MASK_CD
+
+This is a mask of sources that are currently passed through to the
+outputs. Those sources whose bits are not set are muted.
+
+==============================================================================
+GAIN CONTROL
+
+There are five gain controls listed above. Each has 16, 32, or 64
+steps. Each control has 1.5 dB of gain per step. Each control is
+stereo.
+
+The OSS defines the argument to a channel gain ioctl as having two
+components, left and right, each of which ranges from 0 to 100. The
+two components are packed into the same word, with the left side gain
+in the least significant byte, and the right side gain in the second
+least significant byte. In C, we would say this.
+
+ #include <assert.h>
+
+ ...
+
+ assert(leftgain >= 0 && leftgain <= 100);
+ assert(rightgain >= 0 && rightgain <= 100);
+ arg = leftgain | rightgain << 8;
+
+So each OSS gain control has 101 steps. But the hardware has 16, 32,
+or 64 steps. The hardware steps are spread across the 101 OSS steps
+nearly evenly. The conversion formulas are like this, given N equals
+16, 32, or 64.
+
+ int round = N/2 - 1;
+ OSS_gain_steps = (hw_gain_steps * 100 + round) / (N - 1);
+ hw_gain_steps = (OSS_gain_steps * (N - 1) + round) / 100;
+
+Here is a snippet of C code that will return the left and right gain
+of any channel in dB. Pass it one of the predefined gain_desc_t
+structures to access any of the five channels' gains.
+
+ typedef struct gain_desc {
+ float min_gain;
+ float gain_step;
+ int nbits;
+ int chan;
+ } gain_desc_t;
+
+ const gain_desc_t gain_pcm = { -82.5, 1.5, 6, SOUND_MIXER_PCM };
+ const gain_desc_t gain_line = { -34.5, 1.5, 5, SOUND_MIXER_LINE };
+ const gain_desc_t gain_mic = { -34.5, 1.5, 5, SOUND_MIXER_MIC };
+ const gain_desc_t gain_cd = { -34.5, 1.5, 5, SOUND_MIXER_CD };
+ const gain_desc_t gain_reclev = { 0.0, 1.5, 4, SOUND_MIXER_RECLEV };
+
+ int get_gain_dB(int fd, const gain_desc_t *gp,
+ float *left, float *right)
+ {
+ int word;
+ int lg, rg;
+ int mask = (1 << gp->nbits) - 1;
+
+ if (ioctl(fd, MIXER_READ(gp->chan), &word) != 0)
+ return -1; /* fail */
+ lg = word & 0xFF;
+ rg = word >> 8 & 0xFF;
+ lg = (lg * mask + mask / 2) / 100;
+ rg = (rg * mask + mask / 2) / 100;
+ *left = gp->min_gain + gp->gain_step * lg;
+ *right = gp->min_gain + gp->gain_step * rg;
+ return 0;
+ }
+
+And here is the corresponding routine to set a channel's gain in dB.
+
+ int set_gain_dB(int fd, const gain_desc_t *gp, float left, float right)
+ {
+ float max_gain =
+ gp->min_gain + (1 << gp->nbits) * gp->gain_step;
+ float round = gp->gain_step / 2;
+ int mask = (1 << gp->nbits) - 1;
+ int word;
+ int lg, rg;
+
+ if (left < gp->min_gain || right < gp->min_gain)
+ return EINVAL;
+ lg = (left - gp->min_gain + round) / gp->gain_step;
+ rg = (right - gp->min_gain + round) / gp->gain_step;
+ if (lg >= (1 << gp->nbits) || rg >= (1 << gp->nbits))
+ return EINVAL;
+ lg = (100 * lg + mask / 2) / mask;
+ rg = (100 * rg + mask / 2) / mask;
+ word = lg | rg << 8;
+
+ return ioctl(fd, MIXER_WRITE(gp->chan), &word);
+ }
+
OpenPOWER on IntegriCloud