16 files changed, 10233 insertions, 0 deletions

diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt
new file mode 100644
index 000000000000..71ef0498d5e0
--- /dev/null
+++ b/Documentation/sound/alsa/ALSA-Configuration.txt
@@ -0,0 +1,1505 @@
+
+                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.
+    device_mode
+                - permission mask for dynamic sound device filesystem
+                - This is available only when DEVFS is enabled
+                - Default: 0666
+                - E.g.: device_mode=0660
+
+  
+  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.
+
+    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 7 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-ad1816a
+  ------------------
+
+    Module for sound cards based on Analog Devices AD1816A/AD1815 ISA chips.
+
+    port        - port # for AD1816A chip (PnP setup)
+    mpu_port    - port # for MPU-401 UART (PnP setup)
+    fm_port     - port # for OPL3 (PnP setup)
+    irq         - IRQ # for AD1816A chip (PnP setup)
+    mpu_irq     - IRQ # for MPU-401 UART (PnP setup)
+    dma1        - first DMA # for AD1816A chip (PnP setup)
+    dma2        - second DMA # for AD1816A chip (PnP setup)
+    
+    Module supports up to 8 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)
+    
+    Module supports up to 8 cards. This module does not support autoprobe
+    thus main port must be specified!!! Other ports are optional.
+    
+  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
+
+    Module supports autoprobe and multiple chips (max 8).
+
+    The power-management is supported.
+
+  Module snd-als100
+  -----------------
+
+    Module for sound cards based on Avance Logic ALS100/ALS120 ISA chips.
+
+    port        - port # for ALS100 (SB16) chip (PnP setup)
+    irq         - IRQ # for ALS100 (SB16) chip (PnP setup)
+    dma8        - 8-bit DMA # for ALS100 (SB16) chip (PnP setup)
+    dma16       - 16-bit DMA # for ALS100 (SB16) chip (PnP setup)
+    mpu_port    - port # for MPU-401 UART (PnP setup)
+    mpu_irq     - IRQ # for MPU-401 (PnP setup)
+    fm_port     - port # for OPL3 FM (PnP setup)
+    
+    Module supports up to 8 cards, autoprobe and PnP.
+
+  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
+    
+    Module supports up to 8 cards, autoprobe and PnP.
+
+  Module snd-atiixp
+  -----------------
+
+    Module for ATI IXP 150/200/250 AC97 controllers.
+
+    ac97_clock          - AC'97 clock (defalut = 48000)
+    ac97_quirk          - AC'97 workaround for strange hardware
+                          See the description of intel8x0 module for details.
+    spdif_aclink        - S/PDIF transfer over AC-link (default = 1)
+
+    This module supports up to 8 cards and autoprobe.
+
+  Module snd-atiixp-modem
+  -----------------------
+
+    Module for ATI IXP 150/200/250 AC97 modem controllers.
+
+    Module supports up to 8 cards.
+
+    Note: The default index value of this module is -2, i.e. the first
+          slot is excluded.
+
+  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 applicactions don't handle the SPDIF samplerate 
+           control correctly. If you have problems regarding this, try
+           another ALSA compliant mixer (alsamixer works).
+
+  Module snd-azt2320
+  ------------------
+
+    Module for sound cards based on Aztech System AZT2320 ISA chip (PnP only).
+
+    port        - port # for AZT2320 chip (PnP setup)
+    wss_port    - port # for WSS (PnP setup)
+    mpu_port    - port # for MPU-401 UART (PnP setup)
+    fm_port     - FM port # for AZT2320 chip (PnP setup)
+    irq         - IRQ # for AZT2320 (WSS) chip (PnP setup)
+    mpu_irq     - IRQ # for MPU-401 UART (PnP setup)
+    dma1        - 1st DMA # for AZT2320 (WSS) chip (PnP setup)
+    dma2        - 2nd DMA # for AZT2320 (WSS) chip (PnP setup)
+    
+    Module supports up to 8 cards, PnP and autoprobe.
+    
+  Module snd-azt3328
+  ------------------
+
+    Module for sound cards based on Aztech AZF3328 PCI chip.
+
+    joystick    - Enable joystick (default off)
+
+    Module supports up to 8 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
+
+    Module supports up to 8 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
+
+    Module supports up to 8 cards.
+
+
+  Module snd-cmi8330
+  ------------------
+
+    Module for sound cards based on C-Media CMI8330 ISA chips.
+
+    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)
+
+    Module supports up to 8 cards and autoprobe.
+
+  Module snd-cmipci
+  -----------------
+
+    Module for C-Media CMI8338 and 8738 PCI sound cards.
+
+    mpu_port    - 0x300,0x310,0x320,0x330, 0 = disable (default)
+    fm_port     - 0x388 (default), 0 = disable (default)
+    soft_ac3    - Sofware-conversion of raw SPDIF packets (model 033 only)
+                  (default = 1)
+    joystick_port - Joystick port address (0 = disable, 1 = auto-detect)
+
+    Module supports autoprobe and multiple chips (max 8).
+    
+  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
+    
+    Module supports up to 8 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.
+
+    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
+    isapnp      - ISA PnP detection - 0 = disable, 1 = enable (default)
+    
+    Module supports up to 8 cards. This module does not support autoprobe
+    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.
+
+    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
+    isapnp      - ISA PnP detection - 0 = disable, 1 = enable (default)
+    
+    Module supports up to 8 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)
+
+    Module supports up to 8 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 amplifer.
+    thinkpad         - Force to enable Thinkpad's CLKRUN control.
+    mmap_valid       - Support OSS mmap mode (default = 0).
+
+    Module supports up to 8 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-dt019x
+  -----------------
+
+    Module for Diamond Technologies DT-019X / Avance Logic ALS-007 (PnP
+    only)
+
+    port        - Port # (PnP setup)
+    mpu_port    - Port # for MPU-401 (PnP setup)
+    fm_port     - Port # for FM OPL-3 (PnP setup)
+    irq         - IRQ # (PnP setup)
+    mpu_irq     - IRQ # for MPU-401 (PnP setup)
+    dma8        - DMA # (PnP setup)
+
+    Module supports up to 8 cards.  This module is enabled only with
+    ISA PnP support.
+
+  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).
+
+  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
+
+    Module supports up to 8 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]
+    
+  Module snd-emu10k1x
+  -------------------
+
+    Module for Creative Emu10k1X (SB Live Dell OEM version)
+
+    Module supports up to 8 cards.
+
+  Module snd-ens1370
+  ------------------
+
+    Module for Ensoniq AudioPCI ES1370 PCI sound cards.
+                        * SoundBlaster PCI 64
+                        * SoundBlaster PCI 128
+
+    joystick            - Enable joystick (default off)
+
+    Module supports up to 8 cards and autoprobe.
+    
+  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
+
+    Module supports up to 8 cards and autoprobe.
+    
+  Module snd-es968
+  ----------------
+
+    Module for sound cards based on ESS ES968 chip (PnP only).
+
+    port        - port # for ES968 (SB8) chip (PnP setup)
+    irq         - IRQ # for ES968 (SB8) chip (PnP setup)
+    dma1        - DMA # for ES968 (SB8) chip (PnP setup)
+    
+    Module supports up to 8 cards, PnP and autoprobe.
+    
+  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)
+
+    Module supports up to 8 cards and autoprobe (without MPU-401 port).
+
+  Module snd-es18xx
+  -----------------
+
+    Module for ESS AudioDrive ES-18xx sound cards.
+
+    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)
+    isapnp      - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+    Module supports up to 8 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.
+
+    Module supports up to 8 cards and autoprobe.
+
+  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)       
+
+    Module supports up to 8 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)
+
+    Module supports up to 8 cards and autoprobe.
+    
+  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
+
+    Module supports up to 8 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
+
+    Module supports up to 8 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
+
+    Module supports up to 8 cards and autoprobe.
+    
+  Module snd-hda-intel
+  --------------------
+
+    Module for Intel HD Audio (ICH6, ICH6M, ICH7)
+
+    model       - force the model name
+
+    Module supports up to 8 cards.
+
+    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
+          w810          3-jack
+
+        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
+
+  Module snd-hdsp
+  ---------------
+
+    Module for RME Hammerfall DSP audio interface(s)
+
+    Module supports up to 8 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.
+
+  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
+                        * Hoontech SoundTrack DSP 24
+                        * Hoontech SoundTrack DSP 24 Value
+                        * Hoontech SoundTrack DSP 24 Media 7.1
+                        * Digigram VX442
+
+    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
+    omni        - Omni I/O support for MidiMan M-Audio Delta44/66
+    cs8427_timeout - reset timeout for the CS8427 chip (S/PDIF transciever)
+                     in msec resolution, default value is 500 (0.5 sec)
+
+    Module supports up to 8 cards and autoprobe. Note: The consumer part
+    is not used with all Envy24 based cards (for example in the MidiMan Delta
+    serie).
+
+  Module snd-ice1724
+  ------------------
+
+    Module for Envy24HT (VT/ICE1724) based PCI sound cards.
+                        * MidiMan M Audio Revolution 7.1
+                        * AMP Ltd AUDIO2000
+                        * TerraTec Aureon Sky-5.1, Space-7.1
+
+    model       - Use the given board model, one of the following:
+                  revo71, amp2000, prodigy71, aureon51, aureon71,
+                  k8x800
+
+    Module supports up to 8 cards and autoprobe.
+
+  Module snd-intel8x0
+  -------------------
+
+    Module for AC'97 motherboards from Intel and compatibles.
+                        * Intel i810/810E, i815, i820, i830, i84x, MX440
+                        * SiS 7012 (SiS 735)
+                        * NVidia NForce, NForce2
+                        * AMD AMD768, AMD8111
+                        * ALi m5455
+
+    ac97_clock    - AC'97 codec clock base (0 = auto-detect)
+    ac97_quirk    - AC'97 workaround for strange hardware
+                    The following strings are accepted:
+                      default = don't override the default setting
+                      disable = disable the quirk
+                      hp_only = use headphone control as master
+                      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.
+    buggy_irq     - Enable workaround for buggy interrupts on some
+                    motherboards (default off)
+
+    Module supports autoprobe and multiple bus-master chips (max 8).
+
+    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 ac97_quirk option is used to enable/override the workaround
+    for specific devices.  Some hardware have swapped output pins
+    between Master and Headphone, or Surround.  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 power-management is supported.
+    
+  Module snd-intel8x0m
+  --------------------
+
+    Module for Intel ICH (i8x0) chipset MC97 modems.
+
+    ac97_clock    - AC'97 codec clock base (0 = auto-detect)
+
+    This module supports up to 8 cards and autoprobe.
+
+    Note: The default index value of this module is -2, i.e. the first
+          slot is excluded.
+
+  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.
+  
+    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)
+    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
+
+    Module supports up to 8 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.
+  
+    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)
+    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
+
+    Module supports up to 8 cards, autoprobe and ISA PnP.
+
+  Module snd-korg1212
+  -------------------
+
+    Module for Korg 1212 IO PCI card
+
+    Module supports up to 8 cards.
+
+  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) 
+
+    Module supports autoprobe and multiple chips (max 8).
+
+    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-mixart
+  -----------------
+
+    Module for Digigram miXart8 sound cards.
+
+    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-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)
+
+    Module supports multiple devices (max 8) 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-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
+
+    Module supports autoprobe and multiple chips (max 8).
+
+    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 explicity via
+    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 speicfy 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: 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.
+
+    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
+    isapnp      - ISA PnP detection - 0 = disable, 1 = enable (default)
+    
+    Module supports up to 8 cards and ISA PnP. This module 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.
+    
+    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.
+    
+    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.
+    
+    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-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-rme32
+  ----------------
+
+    Module for RME Digi32, Digi32 Pro and Digi32/8 (Sek'd Prodif32, 
+    Prodif96 and Prodif Gold) sound cards.
+
+    Module supports up to 8 cards.
+
+  Module snd-rme96
+  ----------------
+
+    Module for RME Digi96, Digi96/8 and Digi96/8 PRO/PAD/PST sound cards.
+
+    Module supports up to 8 cards.
+
+  Module snd-rme9652
+  ------------------
+
+    Module for RME Digi9652 (Hammerfall, Hammerfall-Light) sound cards.
+
+    precise_ptr - Enable precise pointer (doesn't work reliably).
+                  (default = 0)
+
+    Module supports up to 8 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.
+
+  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.
+
+  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)
+
+    Module supports up to 8 cards and autoprobe.
+    
+  Module snd-sb16 and snd-sbawe
+  -----------------------------
+
+    Module for 16-bit SoundBlaster cards: SoundBlaster 16 (PnP),
+                                          SoundBlaster AWE 32 (PnP),
+                                          SoundBlaster AWE 64 PnP
+
+    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)
+    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)
+    
+    Module supports up to 8 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.
+    
+  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 #
+
+    Module supports up to 8 cards.
+
+  Module snd-sscape
+  -----------------
+
+    Module for ENSONIQ SoundScape PnP cards.
+
+    port        - Port # (PnP setup)
+    irq         - IRQ # (PnP setup)
+    mpu_irq     - MPU-401 IRQ # (PnP setup)
+    dma         - DMA # (PnP setup)
+
+    Module supports up to 8 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.
+
+    Module supports up to 8 cards.
+
+  Module snd-sun-cs4231 (on sparc only)
+  -------------------------------------
+
+    Module for CS4231 sound chips found on Sparcs.
+
+    Module supports up to 8 cards.
+
+  Module snd-wavefront
+  --------------------
+
+    Module for Turtle Beach Maui, Tropez and Tropez+ sound cards.
+
+    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).
+    use_cs4232_midi - Use CS4232 MPU-401 interface
+                      (inaccessibly located inside your computer)
+    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.
+    isapnp          - ISA PnP detection - 0 = disable, 1 = enable (default)
+
+    Module supports up to 8 cards and ISA PnP.
+
+  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)
+    
+    Module supports up to 8 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
+    
+    Module supports up to 8 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
+
+    pcm_channels   - max channels (voices) reserved for PCM
+    wavetable_size - max wavetable size in kB (4-?kb)
+
+    Module supports up to 8 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)
+
+    This module supports up to 8 cards, autoprobe and hotplugging.
+
+  Module snd-usb-usx2y
+  --------------------
+
+    Module for Tascam USB US-122, US-224 and US-428 devices.
+
+    This module supports up to 8 cards, 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 (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 (defalut), 1 = enable, 2 = disable,
+                  3 = 48k only, 4 = no VRA
+                  [VIA8233/C,8235 only]
+    ac97_quirk  - AC'97 workaround for strange hardware
+                  See the description of intel8x0 module for details.
+
+    Module supports autoprobe and multiple bus-master chips (max 8).
+
+    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 (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.
+          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=1 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 it doesn't work, try dxs_support=4.  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.
+
+    Note: for the MPU401 on VIA823x, use snd-mpu401 driver
+          additonally.  The mpu_port option is for VIA686 chips only.
+
+  Module snd-via82xx-modem
+  ------------------------
+
+    Module for VIA82xx AC97 modem
+
+    ac97_clock  - AC'97 codec clock base (default 48000Hz)
+
+    Module supports up to 8 cards.
+
+    Note: The default index value of this module is -2, i.e. the first
+          slot is excluded.
+
+  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-8, default=4)
+    
+    Module supports up to 8 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)
+
+    Module supports up to 8 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.
+
+  Module snd-vxpocket
+  -------------------
+
+    Module for Digigram VX-Pocket VX2 PCMCIA card.
+
+    ibl      - Capture IBL size. (default = 0, minimum size)
+
+    Module supports up to 8 cards.  The module is compiled only when
+    PCMCIA is supported on 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.
+
+    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: the driver is build only when CONFIG_ISA is set.
+    
+  Module snd-vxp440
+  -----------------
+
+    Module for Digigram VX-Pocket 440 PCMCIA card.
+
+    ibl      - Capture IBL size. (default = 0, minimum size)
+
+    Module supports up to 8 cards.  The module is compiled only when
+    PCMCIA is supported on kernel.
+
+    To activate the driver via the card manager, you'll need to set
+    up /etc/pcmcia/vxp440.conf.  See the sound/pcmcia/vx/vxp440.c.
+
+    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: the driver is build only when CONFIG_ISA is set.
+    
+  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)
+
+    Module supports autoprobe and multiple chips (max 8).
+
+    The power-management is supported.
+
+  Module snd-pdaudiocf
+  --------------------
+
+    Module for Sound Core PDAudioCF sound card.
+
+    Note: the driver is build only when CONFIG_ISA is set.
+
+
+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 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/moprobe.conf
+
+In this example, the interwave card is always loaded as the first card
+(index 0) and ens1371 as the second (index 1).
+
+
+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.
+
+
+DEVFS support
+=============
+
+The ALSA driver fully supports the devfs extension.
+You should add lines below to your devfsd.conf file:
+
+LOOKUP snd MODLOAD ACTION snd
+REGISTER ^sound/.* PERMISSIONS root.audio 660
+REGISTER ^snd/.* PERMISSIONS root.audio 660
+
+Warning: These lines assume that you have the audio group in your system.
+         Otherwise replace audio word with another group name (root for
+         example).
+
+
+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
+
+  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
+
+
+Links
+=====
+
+  ALSA project homepage
+       http://www.alsa-project.org
+
diff --git a/Documentation/sound/alsa/Audigy-mixer.txt b/Documentation/sound/alsa/Audigy-mixer.txt
new file mode 100644
index 000000000000..5132fd95e074
--- /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 acticle 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/Bt87x.txt b/Documentation/sound/alsa/Bt87x.txt
new file mode 100644
index 000000000000..11edb2fd2a5a
--- /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@lists.sf.net>, 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 000000000000..4a7df771b806
--- /dev/null
+++ b/Documentation/sound/alsa/CMIPCI.txt
@@ -0,0 +1,242 @@
+              Brief Notes on C-Media 8738/8338 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 difference between two DACs.
+
+- The first DAC supports U8 and S16LE formats, while the second DAC
+  supports only S16LE.
+- The seconde 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 programmin 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 As Rear"       - As mentioned above, the line-in jack is used
+        for the rear (3th and 4th channels) output.
+"Line-In As Bass"       - The line-in jack is used for the bass (5th
+        and 6th channels) output.
+"Mic As Center/LFE"     - The mic jack is used for the bass output.
+        If this switch is on, you cannot use a microphone as a capture
+        source, of course.
+
+
+Digital I/O
+-----------
+
+The CM8x38 provides the excellent SPDIF capability with very chip
+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.  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
+---------------
+
+The MPU401-UART interface is enabled as default only for the first
+(CMIPCI) card.  You need to set module option "midi_port" properly
+for the 2nd (CMIPCI) card.
+
+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..
+
+
+Joystick and Modem
+------------------
+
+The joystick and modem should be available by enabling the control
+switch "Joystick" and "Modem" respectively.  But I myself have never
+tested them yet.
+
+
+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 000000000000..5b18298e9495
--- /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 000000000000..1f3ae3e32d69
--- /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 Managment</title>
+!Esound/core/init.c
+     </sect1>
+     <sect1><title>Device Components</title>
+!Esound/core/device.c
+     </sect1>
+     <sect1><title>KMOD 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 Managment</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 000000000000..e789475304b6
--- /dev/null
+++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
@@ -0,0 +1,6045 @@
+<!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>March 6, 2005</date>
+     <edition>0.3.4</edition>
+
+    <abstract>
+      <para>
+        This document describes how to write an ALSA (Advanced Linux
+        Sound Architecture) driver.
+      </para>
+    </abstract>
+
+    <legalnotice>
+    <para>
+    Copyright (c) 2002-2004  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 the PCI soundcard.
+      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>
+    The target of this document is ones who already have enough
+    skill of C language and have the basic knowledge of linux
+    kernel programming.  This document doesn't explain the general
+    topics of linux kernel codes and doesn't cover the detail of
+    implementation of each low-level driver.  It describes only how is
+    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, you
+    can check the drivers such as <filename>es1938.c</filename> or
+    <filename>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 feedbacks 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 the 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 codes 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 the ALSA driver on the outside of Linux
+      kernel like configure script, the 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 (eventually 2.6 kernel tree) once 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, that 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 core/seq/oss 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 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 the 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 reason :) 
+      </para>
+    </section>
+
+    <section id="file-tree-drivers-directory">
+      <title>drivers directory</title>
+      <para>
+        This directory contains the codes shared among different drivers
+      on the 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 are the codes 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 codes 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
+        synth/emux sub-directory. 
+        </para>
+    </section>
+
+    <section id="file-tree-pci-directory">
+      <title>pci directory</title>
+      <para>
+        This and its sub-directories hold the top-level card modules
+      for PCI soundcards and the codes specific to the PCI BUS.
+      </para>
+
+      <para>
+        The drivers compiled from a single file is stored directly on
+      pci directory, while the drivers with several source files are
+      stored on its own sub-directory (e.g. emu10k1, ice1712). 
+      </para>
+    </section>
+
+    <section id="file-tree-isa-directory">
+      <title>isa directory</title>
+      <para>
+        This 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>
+        These are for the top-level card modules which are
+      specific to each given architecture. 
+      </para>
+    </section>
+
+    <section id="file-tree-usb-directory">
+      <title>usb directory</title>
+      <para>
+        This contains the USB-audio driver. On the latest version, the
+      USB MIDI driver is integrated together with 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 on pci directory, because its API is identical
+      with the standard PCI cards. 
+      </para>
+    </section>
+
+    <section id="file-tree-oss-directory">
+      <title>oss directory</title>
+      <para>
+        The OSS/Lite source files are stored here on Linux 2.6 (or
+      later) tree. (In the ALSA driver tarball, it's 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 of PCI soundcard is like the following:
+
+        <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 pci_driver table which contains the three pointers above.</para></listitem>
+          <listitem><para>create <function>init()</function> function just calling <function>pci_module_init()</function> to register the pci_driver table defined above.</para></listitem>
+          <listitem><para>create <function>exit()</function> function to call <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
+      succeeding sections. The numbers in comment lines of
+      <function>snd_mychip_probe()</function> function are the
+      markers. 
+
+        <example>
+          <title>Basic Flow for PCI Drivers Example</title>
+          <programlisting>
+<![CDATA[
+  #include <sound/driver.h>
+  #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") */
+  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 */
+  typedef struct snd_mychip mychip_t;
+  struct snd_mychip {
+          snd_card_t *card;
+          // rest of implementation will be in the section
+          // "PCI Resource Managements"
+  };
+
+  /* chip-specific destructor
+   * (see "PCI Resource Managements")
+   */
+  static int snd_mychip_free(mychip_t *chip)
+  {
+          .... // will be implemented later...
+  }
+
+  /* component-destructor
+   * (see "Management of Cards and Components")
+   */
+  static int snd_mychip_dev_free(snd_device_t *device)
+  {
+          mychip_t *chip = device->device_data;
+          return snd_mychip_free(chip);
+  }
+
+  /* chip-specific constructor
+   * (see "Management of Cards and Components")
+   */
+  static int __devinit snd_mychip_create(snd_card_t *card,
+                                         struct pci_dev *pci,
+                                         mychip_t **rchip)
+  {
+          mychip_t *chip;
+          int err;
+          static snd_device_ops_t ops = {
+                 .dev_free = snd_mychip_dev_free,
+          };
+
+          *rchip = NULL;
+
+          // check PCI availability here
+          // (see "PCI Resource Managements")
+          ....
+
+          /* allocate a chip-specific data with zero filled */
+          chip = kcalloc(1, sizeof(*chip), GFP_KERNEL);
+          if (chip == NULL)
+                  return -ENOMEM;
+
+          chip->card = card;
+
+          // rest of initialization here; will be implemented
+          // later, see "PCI Resource Managements"
+          ....
+
+          if ((err = snd_device_new(card, SNDRV_DEV_LOWLEVEL,
+                                    chip, &ops)) < 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;
+          snd_card_t *card;
+          mychip_t *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) */
+          if ((err = snd_mychip_create(card, pci, &chip)) < 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) */
+          if ((err = snd_card_register(card)) < 0) {
+                  snd_card_free(card);
+                  return err;
+          }
+
+          /* (7) */
+          pci_set_drvdata(pci, card);
+          dev++;
+          return 0;
+  }
+
+  /* destructor -- see "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 probe callback. The
+      probe callback and other component-constructors which are called
+      from probe callback should be defined with
+      <parameter>__devinit</parameter> prefix. You 
+      cannot use <parameter>__init</parameter> prefix for them,
+      because any PCI device could be a hotplug device. 
+      </para>
+
+      <para>
+        In the probe 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>
+          At each time probe 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[
+  snd_card_t *card;
+  ....
+  card = snd_card_new(index[dev], id[dev], THIS_MODULE, 0);
+]]>
+            </programlisting>
+          </informalexample>
+        </para>
+
+        <para>
+          The detail 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[
+  mychip_t *chip;
+  ....
+  if ((err = snd_mychip_create(card, pci, &chip)) < 0) {
+          snd_card_free(card);
+          return err;
+  }
+]]>
+            </programlisting>
+          </informalexample>
+
+          The detail will be explained in the section <link
+        linkend="pci-resource"><citetitle>PCI Resource
+        Managements</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 referred 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 which is
+        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[
+  if ((err = snd_card_register(card)) < 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
+        referred 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 <sound/driver.h>
+  #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 codes are split to several
+      files, the file without module options don't need them.
+      </para>
+
+      <para>
+        In addition to them, you'll need
+      <filename>&lt;linux/interrupt.h&gt;</filename> for the interrupt
+      handling, and <filename>&lt;asm/io.h&gt;</filename> for the i/o
+      access. If you use <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 PCM or control API are defined in other
+      header files as <filename>&lt;sound/xxx.h&gt;</filename>.
+      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 list of whole 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 proper releases of resources at
+      destruction. 
+      </para>
+
+      <para>
+        As mentioned above, to create a card instance, call
+      <function>snd_card_new()</function>.
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  snd_card_t *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 this data
+        <emphasis>is</emphasis> 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. On ALSA driver, a component is
+      represented as a <type>snd_device_t</type> object.
+      A component can be a PCM instance, a control interface, a raw
+      MIDI interface, etc.  Each of such instances 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 of 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 identifier
+      (<parameter>chip</parameter> in the above example) for the
+      instance. 
+      </para>
+
+      <para>
+        Each ALSA pre-defined component such as ac97 or 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 would like to create your own component, you need to
+      set the destructor function to dev_free callback in
+      <parameter>ops</parameter>, so that it can be released
+      automatically via <function>snd_card_free()</function>. The
+      example will be shown later as an implementation of a
+      chip-specific data. 
+      </para>
+    </section>
+
+    <section id="card-management-chip-specific">
+      <title>Chip-Specific Data</title>
+      <para>
+      The chip-specific information, e.g. the i/o port address, its
+      resource pointer, or the irq number, is stored in the
+      chip-specific record.
+      Usually, the chip-specific record is typedef'ed as
+      <type>xxx_t</type> like the following:
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  typedef struct snd_mychip mychip_t;
+  struct snd_mychip {
+          ....
+  };
+]]>
+          </programlisting>
+        </informalexample>
+      </para>
+
+      <para>
+        In general, there are two ways to allocate 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(mychip_t));
+]]>
+            </programlisting>
+          </informalexample>
+
+          whether <type>mychip_t</type> is the type of the chip record.
+        </para>
+
+        <para>
+          In return, the allocated record can be accessed as
+
+          <informalexample>
+            <programlisting>
+<![CDATA[
+  mychip_t *chip = (mychip_t *)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>kcalloc()</function>. 
+
+          <informalexample>
+            <programlisting>
+<![CDATA[
+  snd_card_t *card;
+  mychip_t *chip;
+  card = snd_card_new(index[dev], id[dev], THIS_MODULE, NULL);
+  .....
+  chip = kcalloc(1, 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 snd_mychip {
+          snd_card_t *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 snd_device_ops_t 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(snd_device_t *device)
+  {
+          mychip_t *chip = device->device_data;
+          return snd_mychip_free(chip);
+  }
+]]>
+            </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>. The access
+      to the device files are 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 already mentioned, 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
+      <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_in_thread</function>.  This one will
+      postpone the destruction and wait in a kernel-thread until all
+      devices are closed.
+      </para>
+
+    </section>
+
+  </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- PCI Resource Managements  -->
+<!-- ****************************************************** -->
+  <chapter id="pci-resource">
+    <title>PCI Resource Managements</title>
+
+    <section id="pci-resource-example">
+      <title>Full Code Example</title>
+      <para>
+        In this section, we'll finish the chip-specific constructor,
+      destructor and PCI entries. The example code is shown first,
+      below. 
+
+        <example>
+          <title>PCI Resource Managements Example</title>
+          <programlisting>
+<![CDATA[
+  struct snd_mychip {
+          snd_card_t *card;
+          struct pci_dev *pci;
+
+          unsigned long port;
+          int irq;
+  };
+
+  static int snd_mychip_free(mychip_t *chip)
+  {
+          /* disable hardware here if any */
+          .... // (not implemented in this document)
+
+          /* release the irq */
+          if (chip->irq >= 0)
+                  free_irq(chip->irq, (void *)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(snd_card_t *card,
+                                         struct pci_dev *pci,
+                                         mychip_t **rchip)
+  {
+          mychip_t *chip;
+          int err;
+          static snd_device_ops_t ops = {
+                 .dev_free = snd_mychip_dev_free,
+          };
+
+          *rchip = NULL;
+
+          /* initialize the PCI entry */
+          if ((err = pci_enable_device(pci)) < 0)
+                  return err;
+          /* check PCI availability (28bit DMA) */
+          if (pci_set_dma_mask(pci, 0x0fffffff) < 0 ||
+              pci_set_consistent_dma_mask(pci, 0x0fffffff) < 0) {
+                  printk(KERN_ERR "error to set 28bit mask DMA\n");
+                  pci_disable_device(pci);
+                  return -ENXIO;
+          }
+
+          chip = kcalloc(1, 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 */
+          if ((err = pci_request_regions(pci, "My Chip")) < 0) {
+                  kfree(chip);
+                  pci_disable_device(pci);
+                  return err;
+          }
+          chip->port = pci_resource_start(pci, 0);
+          if (request_irq(pci->irq, snd_mychip_interrupt,
+                          SA_INTERRUPT|SA_SHIRQ, "My Chip",
+                          (void *)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)
+
+          if ((err = snd_device_new(card, SNDRV_DEV_LOWLEVEL,
+                                    chip, &ops)) < 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),
+  };
+
+  /* initialization of the module */
+  static int __init alsa_card_mychip_init(void)
+  {
+          return pci_module_init(&driver);
+  }
+
+  /* clean up the module */
+  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 have to call at first
+      <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[
+  if ((err = pci_enable_device(pci)) < 0)
+          return err;
+  if (pci_set_dma_mask(pci, 0x0fffffff) < 0 ||
+      pci_set_consistent_dma_mask(pci, 0x0fffffff) < 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 are 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 ALSA 0.5.x. 
+      </para>
+
+      <para>
+        Now assume that this PCI device has an I/O port with 8 bytes
+        and an interrupt. Then <type>mychip_t</type> will have the
+        following fields: 
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  struct snd_mychip {
+          snd_card_t *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>kcalloc()</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[
+  if ((err = pci_request_regions(pci, "My Chip")) < 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 some
+      problem regarding this. This issue will be explained more below.
+      </para>
+
+      <para>
+        The allocation of an interrupt source is done like this:
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  if (request_irq(pci->irq, snd_mychip_interrupt,
+                  SA_INTERRUPT|SA_SHIRQ, "My Chip",
+                  (void *)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, the interrupts can be shared. Thus,
+      <constant>SA_SHIRQ</constant> is given 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 define the detail of 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 pt_regs *regs)
+  {
+          mychip_t *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 is not written here. 
+      </para>
+
+      <para>
+        For releasing the resources, <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, (void *)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 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 below:
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  if (chip->res_port) {
+          release_resource(chip->res_port);
+          kfree_nocheck(chip->res_port);
+  }
+]]>
+          </programlisting>
+        </informalexample>
+
+      As you can see, the resource pointer is also to be freed
+      via <function>kfree_nocheck()</function> after
+      <function>release_resource()</function> is called. You
+      cannot use <function>kfree()</function> here, because on ALSA,
+      <function>kfree()</function> may be a wrapper to its own
+      allocator with the memory debugging. Since the resource pointer
+      is allocated externally outside the ALSA, it must be released
+      via the native
+      <function>kfree()</function>.
+      <function>kfree_nocheck()</function> is used for that; it calls
+      the native <function>kfree()</function> without wrapper. 
+      </para>
+
+      <para>
+      Don't forget to call <function>pci_disable_device()</function>
+      before all finished.
+      </para>
+
+      <para>
+        And finally, release the chip-specific record.
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  kfree(chip);
+]]>
+          </programlisting>
+        </informalexample>
+      </para>
+
+      <para>
+      Again, remember that you cannot
+      set <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 the 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 been already released.
+      You don't have to call stopping PCMs, etc. explicitly, but just
+      stop the hardware in the low-level.
+      </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 snd_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(mychip_t *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 <structname>struct 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 rest of missing PCI
+      stuffs. 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
+      <structname>pci_device_id</structname> struct are the vendor and
+      device IDs. If you have nothing special to filter the matching
+      devices, you can use the rest of fields like above. The last
+      field of <structname>pci_device_id</structname> struct is a
+      private data for this entry. You can specify any value here, for
+      example, to tell the type of different operations per each
+      device IDs. Such an example is found in 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 are what we already
+      defined in 
+      the previous sections. The <structfield>remove</structfield> should
+      be defined with 
+      <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_module_init(&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 on 2.2 or 2.4 kernels (on 2.6 kernels
+        it's not necessary, though).
+
+        <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> above all. 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 number. Once when 64bit device number is
+      used, we'll have more available pcm instances. 
+      </para>
+
+      <para>
+        A pcm instance consists of pcm playback and capture streams,
+      and each pcm stream consists of one or more pcm substreams. Some
+      soundcard supports the multiple-playback function. 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 succeeding open will result in the blocking
+      or the error with <constant>EAGAIN</constant> according to the
+      file open mode. But you don't have to know the detail in your
+      driver. The PCM middle layer will take all such jobs. 
+      </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 snd_pcm_hardware_t 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 snd_pcm_hardware_t 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(snd_pcm_substream_t *substream)
+  {
+          mychip_t *chip = snd_pcm_substream_chip(substream);
+          snd_pcm_runtime_t *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(snd_pcm_substream_t *substream)
+  {
+          mychip_t *chip = snd_pcm_substream_chip(substream);
+          // the hardware-specific codes will be here
+          return 0;
+
+  }
+
+  /* open callback */
+  static int snd_mychip_capture_open(snd_pcm_substream_t *substream)
+  {
+          mychip_t *chip = snd_pcm_substream_chip(substream);
+          snd_pcm_runtime_t *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(snd_pcm_substream_t *substream)
+  {
+          mychip_t *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(snd_pcm_substream_t *substream,
+                               snd_pcm_hw_params_t * hw_params)
+  {
+          return snd_pcm_lib_malloc_pages(substream,
+                                     params_buffer_bytes(hw_params));
+  }
+
+  /* hw_free callback */
+  static int snd_mychip_pcm_hw_free(snd_pcm_substream_t *substream)
+  {
+          return snd_pcm_lib_free_pages(substream);
+  }
+
+  /* prepare callback */
+  static int snd_mychip_pcm_prepare(snd_pcm_substream_t *substream)
+  {
+          mychip_t *chip = snd_pcm_substream_chip(substream);
+          snd_pcm_runtime_t *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_area,
+                               chip->buffer_size,
+                               chip->period_size);
+          return 0;
+  }
+
+  /* trigger callback */
+  static int snd_mychip_pcm_trigger(snd_pcm_substream_t *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(snd_pcm_substream_t *substream)
+  {
+          mychip_t *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 snd_pcm_ops_t 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 snd_pcm_ops_t 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(mychip_t *chip)
+  {
+          snd_pcm_t *pcm;
+          int err;
+
+          if ((err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1,
+                                 &pcm)) < 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 <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(mychip_t *chip)
+  {
+          snd_pcm_t *pcm;
+          int err;
+
+          if ((err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1,
+                                 &pcm)) < 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 the 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. When
+      you will 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 both 1 are given in
+      the above example.  When no playback or no capture is 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
+      <type>snd_pcm_substream_t</type> data passed to each callback
+      as follows: 
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  snd_pcm_substream_t *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 snd_pcm_ops_t 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>
+
+        Each of callbacks is explained in the subsection 
+        <link linkend="pcm-interface-operators"><citetitle>
+        Operators</citetitle></link>.
+      </para>
+
+      <para>
+        After setting the operators, most likely you'd like 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 up to 64kB buffer as default. The details of
+      buffer management 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 destructor
+      explicitly.
+      </para>
+
+      <para>
+        The destructor would be necessary when you created some
+        special records internally and need 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(snd_pcm_t *pcm)
+  {
+          mychip_t *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(mychip_t *chip)
+  {
+          snd_pcm_t *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 the various information; it holds
+        the copy of hw_params and sw_params configurations, the buffer
+        pointers, mmap records, spinlocks, etc.  Almost everyhing you
+        need for controlling the PCM can be found there.
+        </para>
+
+        <para>
+        The definition of runtime instance is found in
+        <filename>&lt;sound/pcm.h&gt;</filename>.  Here is the
+        copy from the file.
+          <informalexample>
+            <programlisting>
+<![CDATA[
+struct _snd_pcm_runtime {
+        /* -- Status -- */
+        snd_pcm_substream_t *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 -- */
+        int tstamp_timespec;            /* use timeval (0) or timespec (1) */
+        snd_pcm_tstamp_t tstamp_mode;   /* mmap timestamp is updated */
+        unsigned int period_step;
+        unsigned int sleep_min;         /* min ticks to sleep */
+        snd_pcm_uframes_t xfer_align;   /* xfer size need to be a multiple */
+        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 snd_pcm_mmap_status_t *status;
+        volatile snd_pcm_mmap_control_t *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)(snd_pcm_runtime_t *runtime);
+
+        /* -- hardware description -- */
+        snd_pcm_hardware_t hw;
+        snd_pcm_hw_constraints_t hw_constraints;
+
+        /* -- interrupt callbacks -- */
+        void (*transfer_ack_begin)(snd_pcm_substream_t *substream);
+        void (*transfer_ack_end)(snd_pcm_substream_t *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 -- */
+        snd_pcm_oss_runtime_t 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 these info.  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 (<type>snd_pcm_hardware_t</type>)
+        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[
+          snd_pcm_runtime_t *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 like below:
+          <informalexample>
+            <programlisting>
+<![CDATA[
+  static snd_pcm_hardware_t 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 mmap is supported, add
+        <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
+        hardware supports the interleaved or the non-interleaved
+        format, <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 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 <quote>suspend/resume</quote> operation. If these flags
+        are set, the <structfield>trigger</structfield> callback below
+        must handle the corresponding commands. 
+        </para>
+
+        <para>
+          When the PCM substreams can be synchronized (typically,
+        synchorinized 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
+        <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 minimal and
+        maximal 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 minimal and maximal
+        number of channels.
+        </para>
+        </listitem>
+
+        <listitem>
+        <para>
+        <structfield>buffer_bytes_max</structfield> defines the
+        maximal buffer size in bytes.  There is no
+        <structfield>buffer_bytes_min</structfield> field, since
+        it can be calculated from the minimal period size and the
+        minimal number of periods.
+        Meanwhile, <structfield>period_bytes_min</structfield> and
+        define the minimal and maximal size of the period in bytes.
+        <structfield>periods_max</structfield> and
+        <structfield>periods_min</structfield> define the maximal and
+        minimal number of periods in the buffer.
+        </para>
+
+        <para>
+        The <quote>period</quote> is a term, that corresponds to
+        fragment in the OSS world.  The period defines the size at
+        which the 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 it's not
+        used currently 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 on 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
+        helper functions, <function>frames_to_bytes()</function> and
+          <function>bytes_to_frames()</function>. 
+          <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 not mandatory.  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 <type>snd_pcm_mmap_status_t</type>
+        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
+        <type>snd_pcm_mmap_control_t</type> 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
+        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 the
+        chip instance assigned statically at the creation of PCM, while the 
+        <constant>runtime-&gt;private_data</constant> points a dynamic
+        data created at the PCM open callback.
+
+          <informalexample>
+            <programlisting>
+<![CDATA[
+  static int snd_xxx_open(snd_pcm_substream_t *substream)
+  {
+          my_pcm_data_t *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 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 explain the detail of each pcm callback
+      (<parameter>ops</parameter>). In general, every callback must
+      return 0 if successful, or a negative number with the error
+      number such as <constant>-EINVAL</constant> at any
+      error. 
+      </para>
+
+      <para>
+        The callback function takes at least the argument with
+        <type>snd_pcm_substream_t</type> pointer. For retrieving the
+        chip record from the given substream instance, you can use the
+        following macro. 
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  int xxx() {
+          mychip_t *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, 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(snd_pcm_substream_t *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(snd_pcm_substream_t *substream)
+  {
+          mychip_t *chip = snd_pcm_substream_chip(substream);
+          snd_pcm_runtime_t *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(snd_pcm_substream_t *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(snd_pcm_substream_t *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 action 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(snd_pcm_substream_t * substream,
+                               snd_pcm_hw_params_t * hw_params);
+]]>
+            </programlisting>
+          </informalexample>
+
+          This and <structfield>hw_free</structfield> callbacks exist
+        only on ALSA 0.9.x. 
+        </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 set-up 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. For allocating a
+          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 take care not to allocate the same buffers
+        many times, which will lead to memory leak!  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, mutex 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(snd_pcm_substream_t * 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(snd_pcm_substream_t * 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 at each
+        time 
+        <function>snd_pcm_prepare()</function> is called, i.e. when
+        recovered after underruns, etc. 
+        </para>
+
+        <para>
+        Note that this callback became non-atomic since the recent version.
+        You can use schedule-related fucntions safely in this callback now.
+        </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 set up, too. 
+        </para>
+      </section>
+
+      <section id="pcm-interface-operators-trigger-callback">
+        <title>trigger callback</title>
+        <para>
+          <informalexample>
+            <programlisting>
+<![CDATA[
+  static int snd_xxx_trigger(snd_pcm_substream_t * 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,
+          <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 info
+        field of the hardware table), <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
+        (i.e. <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set),
+        <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>
+        do suspend and resume of the pcm substream, and usually, they
+        are identical with <constant>STOP</constant> and
+        <constant>START</constant> commands, respectively.
+        </para>
+
+        <para>
+          As mentioned, this callback is atomic.  You cannot call
+          the function going to 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(snd_pcm_substream_t * 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 (which was in bytes on ALSA 0.5.x),
+        ranged 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 on 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 also not mandatory. This callback is used
+        mainly for the non-contiguous buffer. 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 <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 aquire 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>
+          A typical coding would be like:
+
+          <example>
+            <title>Interrupt Handler Case #1</title>
+            <programlisting>
+<![CDATA[
+  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id,
+                                          struct pt_regs *regs)
+  {
+          mychip_t *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-frequent timer interrupts</title>
+        <para>
+        This is the case when the hardware doesn't generate interrupts
+        at the period boundary but do timer-interrupts at the fixed
+        timer rate (e.g. es1968 or ymfpci drivers). 
+        In this case, you need to check the current hardware
+        position and accumulates the processed sample length at each
+        interrupt.  When the accumulated size overcomes the period
+        size, call 
+        <function>snd_pcm_period_elapsed()</function> and reset the
+        accumulator. 
+        </para>
+
+        <para>
+          A typical coding 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 pt_regs *regs)
+  {
+          mychip_t *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) problem
+      on the kernel programming is the race condition.
+      On linux kernel, usually it's solved via spin-locks or
+      semaphores.  In general, if the race condition may
+      happen in the interrupt handler, it's handled as atomic, and you
+      have to use spinlock for protecting the critical session.  If it
+      never happens in the interrupt and it may take relatively long
+      time, you should use semaphore.
+      </para>
+
+      <para>
+      As already seen, some pcm callbacks are atomic and some are
+      not.  For example, <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 use a spinlock or a semaphore 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>.  The semaphore and mutex do sleep,
+      and hence they cannot be used inside the atomic callbacks
+      (e.g. <parameter>trigger</parameter> callback).
+      For taking a certain 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 snd_pcm_hw_constraint_list_t constraints_rates = {
+          .count = ARRAY_SIZE(rates),
+          .list = rates,
+          .mask = 0,
+  };
+
+  static int snd_mychip_pcm_open(snd_pcm_substream_t *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 in <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 <type>snd_pcm_hardware_t</type> stucture (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(snd_pcm_hw_params_t *params,
+                                        snd_pcm_hw_rule_t *rule)
+  {
+          snd_interval_t *c = hw_param_interval(params, SNDRV_PCM_HW_PARAM_CHANNELS);
+          snd_mask_t *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
+          snd_mask_t 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(snd_pcm_hw_params_t *params,
+                                        snd_pcm_hw_rule_t *rule)
+  {
+          snd_interval_t *c = hw_param_interval(params, SNDRV_PCM_HW_PARAM_CHANNELS);
+          snd_mask_t *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
+          snd_interval_t 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 explain 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 the user-space. Its most
+      important use is the mixer interface. In other words, on ALSA
+      0.9.x, all the mixer stuff is implemented on the control kernel
+      API (while there was an independent mixer kernel API on 0.5.x). 
+      </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 add your own controls.
+      </para>
+    </section>
+
+    <section id="control-interface-definition">
+      <title>Definition of Controls</title>
+      <para>
+        For creating a new control, you need to define the three
+      callbacks: <structfield>info</structfield>,
+      <structfield>get</structfield> and
+      <structfield>put</structfield>. Then, define a
+      <type>snd_kcontrol_new_t</type> record, such as: 
+
+        <example>
+          <title>Definition of a Control</title>
+          <programlisting>
+<![CDATA[
+  static snd_kcontrol_new_t my_control __devinitdata = {
+          .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
+          .name = "PCM Playback Switch",
+          .index = 0,
+          .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
+          .private_values = 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 <parameter>__devinitdata</parameter> prefix to the
+      definition like above. 
+      </para>
+
+      <para>
+        The <structfield>iface</structfield> field specifies the type of
+      the control,
+      <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>. There are
+      <constant>MIXER</constant>, <constant>PCM</constant>,
+      <constant>CARD</constant>, etc.
+      </para>
+
+      <para>
+        The <structfield>name</structfield> is the name identifier
+      string. On 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 subsection
+      <link linkend="control-interface-control-names"><citetitle>
+      Control Names</citetitle></link>.
+      </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 detailed will be explained in the subsection
+      <link linkend="control-interface-access-flags"><citetitle>
+      Access Flags</citetitle></link>.
+      </para>
+
+      <para>
+        The <structfield>private_values</structfield> field contains
+      an arbitrary long integer value for this record. When using
+      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 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 for defining 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> or
+      <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 bit-flags 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
+      regarded 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
+      <structfield>put</structfield> callback.
+      Similarly, when the control is write-only (although it's a rare
+      case), you can use <constant>WRITE</constant> flag instead, and
+      you don't need <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
+      <constant>INACTIVE</constant> flag, too.
+      There are <constant>LOCK</constant> and
+      <constant>OWNER</constant> flags for changing 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
+        the detailed information of this control. This must store the
+        values of the given <type>snd_ctl_elem_info_t</type>
+        object. For example, for a boolean control with a single
+        element will be: 
+
+          <example>
+            <title>Example of info callback</title>
+            <programlisting>
+<![CDATA[
+  static int snd_myctl_info(snd_kcontrol_t *kcontrol,
+                          snd_ctl_elem_info_t *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 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_info(snd_kcontrol_t *kcontrol,
+                          snd_ctl_elem_info_t *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>
+      </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 the user-space. 
+        </para>
+
+        <para>
+          For example,
+
+          <example>
+            <title>Example of get callback</title>
+            <programlisting>
+<![CDATA[
+  static int snd_myctl_get(snd_kcontrol_t *kcontrol,
+                           snd_ctl_elem_value_t *ucontrol)
+  {
+          mychip_t *chip = snd_kcontrol_chip(kcontrol);
+          ucontrol->value.integer.value[0] = get_some_value(chip);
+          return 0;
+  }
+]]>
+            </programlisting>
+          </example>
+        </para>
+
+        <para>
+          Here, the chip instance is retrieved via
+        <function>snd_kcontrol_chip()</function> macro.  This macro
+        converts from kcontrol-&gt;private_data to the type defined by
+        <type>chip_t</type>. The
+        kcontrol-&gt;private_data field is 
+        given as the argument of <function>snd_ctl_new()</function>
+        (see the later subsection
+        <link linkend="control-interface-constructor"><citetitle>Constructor</citetitle></link>).
+        </para>
+
+        <para>
+        The <structfield>value</structfield> field is depending on
+        the type of control as well as on 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> is set like
+          <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(snd_kcontrol_t *kcontrol,
+                                    snd_ctl_elem_value_t *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 <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 the user-space.
+        </para>
+
+        <para>
+          For example,
+
+          <example>
+            <title>Example of put callback</title>
+            <programlisting>
+<![CDATA[
+  static int snd_myctl_put(snd_kcontrol_t *kcontrol,
+                           snd_ctl_elem_value_t *ucontrol)
+  {
+          mychip_t *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>
+        Like <structfield>get</structfield> callback,
+        when the control has more than one elements,
+        all elemehts 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. For creating 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[
+  if ((err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip))) < 0)
+          return err;
+]]>
+          </programlisting>
+        </informalexample>
+
+        where <parameter>my_control</parameter> is the
+      <type>snd_kcontrol_new_t</type> object defined above, and chip
+      is the object pointer to be passed to
+      kcontrol-&gt;private_data 
+      which can be referred in callbacks. 
+      </para>
+
+      <para>
+        <function>snd_ctl_new1()</function> allocates a new
+      <type>snd_kcontrol_t</type> instance (that's why the definition
+      of <parameter>my_control</parameter> can be with
+      <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 <type>snd_ctl_elem_id_t</type>
+      to be notified.
+      You can find some examples in <filename>es1938.c</filename> or
+      <filename>es1968.c</filename> for hardware volume interrupts. 
+      </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 many codes 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 snd_mychip {
+          ....
+          ac97_t *ac97;
+          ....
+  };
+
+  static unsigned short snd_mychip_ac97_read(ac97_t *ac97,
+                                             unsigned short reg)
+  {
+          mychip_t *chip = ac97->private_data;
+          ....
+          // read a register value here from the codec
+          return the_register_value;
+  }
+
+  static void snd_mychip_ac97_write(ac97_t *ac97,
+                                   unsigned short reg, unsigned short val)
+  {
+          mychip_t *chip = ac97->private_data;
+          ....
+          // write the given register value to the codec
+  }
+
+  static int snd_mychip_ac97(mychip_t *chip)
+  {
+          ac97_bus_t *bus;
+          ac97_template_t ac97;
+          int err;
+          static ac97_bus_ops_t ops = {
+                  .write = snd_mychip_ac97_write,
+                  .read = snd_mychip_ac97_read,
+          };
+
+          if ((err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus)) < 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>
+        For creating 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[
+  ac97_bus_t *bus;
+  static ac97_bus_ops_t 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 <type>ac97_template_t</type>
+      record together with the bus pointer created above.
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  ac97_template_t 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 the pointer of 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.  When 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(ac97_t *ac97,
+                                             unsigned short reg)
+  {
+          mychip_t *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(ac97_t *ac97,
+                       unsigned short reg, unsigned short val)
+]]>
+          </programlisting>
+        </informalexample>
+      </para>
+
+      <para>
+      These callbacks are non-atomic like the callbacks of control API.
+      </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 way of reset, you can
+      define this callback. 
+      </para>
+
+      <para>
+        The <structfield>wait</structfield> callback is used for a
+      certain wait at the standard initialization of the codec. If the
+      chip requires the extra wait-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 of 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
+        certain 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 for setting 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 the
+      <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>
+        On some chip, 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 the auto-measurement function of 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_new()</function> multiple times with
+      ac97.num=1 or greater. The <structfield>num</structfield> field
+      specifies the codec 
+      number. 
+      </para>
+
+      <para>
+        If you have set up multiple codecs, you need to either 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 similar but a little bit different
+      implementation of mpu401 stuff. For example, emu10k1 has its own
+      mpu401 routines. 
+      </para>
+    </section>
+
+    <section id="midi-interface-constructor">
+      <title>Constructor</title>
+      <para>
+        For creating a rawmidi object, call
+      <function>snd_mpu401_uart_new()</function>. 
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  snd_rawmidi_t *rmidi;
+  snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, integrated,
+                      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 has 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>
+        When the i/o port address above is a 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 non-zero
+      to the 5th argument
+      (<parameter>integrated</parameter>). Otherwise, pass 0 to it,
+      and 
+      the mpu401-uart layer will allocate the i/o ports by itself. 
+      </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
+        <type>mpu401_t</type> manually 
+        afterward. However, <type>mpu401_t</type> pointer is not
+        returned explicitly by
+        <function>snd_mpu401_uart_new()</function>. You need to cast
+        rmidi-&gt;private_data to
+        <type>mpu401_t</type> explicitly, 
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  mpu401_t *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 generates
+      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 to do nothing
+      else 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[
+  snd_rawmidi_t *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 substream 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 snd_rawmidi_ops_t 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 is more than one substream, you should give each one a
+      unique name:
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  struct list_head *list;
+  snd_rawmidi_substream_t *substream;
+  list_for_each(list, &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams) {
+          substream = list_entry(list, snd_rawmidi_substream_t, 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 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 snd_rawmidi_substream_t data passed to each
+      callback:
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  snd_rawmidi_substream_t *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(snd_rawmidi_substream_t *substream);
+]]>
+          </programlisting>
+        </informalexample>
+
+        <para>
+        This is called when a substream is opened.
+        You can initialize the hardware here, but you should not yet
+        start transmitting/receiving data.
+        </para>
+      </section>
+
+      <section id="rawmidi-interface-op-close">
+      <title><function>close</function> callback</title>
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  static int snd_xxx_close(snd_rawmidi_substream_t *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(snd_rawmidi_substream_t *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 is no more
+        data in the buffer.
+        After the data has 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 (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 it from the buffer at once:
+          <informalexample>
+            <programlisting>
+<![CDATA[
+  while (mychip_transmit_possible()) {
+          unsigned char data;
+          if (snd_rawmidi_transmit(substream, &data, 1) != 1)
+                  break; /* no more data */
+          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(snd_rawmidi_substream_t *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(snd_rawmidi_substream_t *substream);
+]]>
+          </programlisting>
+        </informalexample>
+
+        <para>
+        This is only used with output substreams.  This function should wait
+        until all data read from the substream buffer has 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 snd_rawmidi_ops_t
+        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 on 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 direct-FM API,
+      defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
+      ALSA native mode, FM registers are accessed through
+      Hardware-Dependant Device direct-FM extension API, whereas in
+      OSS compatible mode, FM registers can be accessed with OSS
+      direct-FM compatible API on <filename>/dev/dmfmX</filename> device. 
+      </para>
+
+      <para>
+        For creating the OPL3 component, you have two functions to
+        call. The first one is a constructor for <type>opl3_t</type>
+        instance. 
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  opl3_t *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, opl3 module will
+      allocate the specified ports by itself. 
+      </para>
+
+      <para>
+        When the accessing to 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[
+  opl3_t *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 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[
+  snd_hwdep_t *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 the access from the user-space 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>
+        Creation of the <type>hwdep</type> instance is done via
+        <function>snd_hwdep_new()</function>. 
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  snd_hwdep_t *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 to
+        <structfield>private_free</structfield> field.  
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  mydata_t *p = kmalloc(sizeof(*p), GFP_KERNEL);
+  hw->private_data = p;
+  hw->private_free = mydata_free;
+]]>
+          </programlisting>
+        </informalexample>
+
+        and the implementation of destructor would be:
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  static void mydata_free(snd_hwdep_t *hw)
+  {
+          mydata_t *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
+        <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
+      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 <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
+      <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 the
+      enough space is found.
+      </para>
+
+      <para>
+      For releasing the space, 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 the
+       construction of pcm instance (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 maximal
+      size to be changed via <filename>prealloc</filename> proc file.
+      The allocator will try to get as large area 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 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,
+      whereh <constant>GFP_KERNEL</constant> is the kernel allocation flag to
+      use.  For the SBUS, <constant>SNDRV_DMA_TYPE_SBUS</constant> and
+      <function>snd_dma_sbus_data(sbus_dev)</function> are used instead.
+      For the PCI scatter-gather buffers, use
+      <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
+      <function>snd_dma_pci_data(pci)</function>
+      (see the section
+          <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
+          </citetitle></link>).
+      </para>
+
+      <para>
+        Once when 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 enough
+      large.  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 the mmap of the buffer, although you have
+      to handle an interrupt or a tasklet for transferring the data
+      from the intermediate buffer to the hardware buffer. You can find an
+      example in vxpocket driver. 
+      </para>
+
+      <para>
+        Another case is that 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 intel. In
+      non-mmap mode, the data cannot be transferred as the normal
+      way. Thus you need to define <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 <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(snd_pcm_substream_t *substream, int channel,
+               snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
+  static int capture_copy(snd_pcm_substream_t *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 case of
+        playback, you do: 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 do: 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 of the position and the data amount 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(snd_pcm_substream_t *substream, int channel,
+                     snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
+]]>
+          </programlisting>
+        </informalexample>
+      </para>
+
+      <para>
+        The meanings of arguments are identical with 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 like emu10k1 or the
+      buffer descriptors like 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 the <function>snd_dma_pci_data(pci)</function>,
+        where pci is the struct <structname>pci_dev</structname> pointer
+        of the chip as well.
+        The <type>snd_sg_buf_t</type> instance is created as
+        substream-&gt;dma_private. You can cast
+        the pointer like: 
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  snd_pcm_sgbuf_t *sgbuf = (snd_pcm_sgbuf_t*)substream->dma_private;
+]]>
+          </programlisting>
+        </informalexample>
+      </para>
+
+      <para>
+        Then call <function>snd_pcm_lib_malloc_pages()</function>
+      in <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>
+        For releasing 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(snd_pcm_substream_t *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>
+      For creating a proc file, call
+      <function>snd_card_proc_new()</function>. 
+
+      <informalexample>
+        <programlisting>
+<![CDATA[
+  snd_info_entry_t *entry;
+  int err = snd_card_proc_new(card, "my-file", &entry);
+]]>
+        </programlisting>
+      </informalexample>
+
+      where the second argument specifies the proc-file name 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 at the pointer given in the third argument.
+    It is initialized as a text proc file for read only.  For using
+    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, read_size, 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(snd_info_entry_t *entry,
+                           snd_info_buffer_t *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(snd_info_entry_t *entry,
+                           snd_info_buffer_t *buffer)
+  {
+          chip_t *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 permission can be changed afterwards.  As default, it's
+    set as read only for all users.  If you want to add the write
+    permission to the user (root as default), set like below:
+
+      <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_size = 256;
+  entry->c.text.write = my_proc_write;
+]]>
+        </programlisting>
+      </informalexample>
+    </para>
+
+    <para>
+    The buffer size for read is set to 1024 implicitly by
+    <function>snd_info_set_text_ops()</function>.  It should suffice
+    in most cases (the size will be aligned to
+    <constant>PAGE_SIZE</constant> anyway), but if you need to handle
+    very large text files, you can set it explicitly, too.
+
+      <informalexample>
+        <programlisting>
+<![CDATA[
+  entry->c.text.read_size = 65536;
+]]>
+        </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 like the following:
+
+      <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(snd_info_entry_t *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 with suspend/resume
+      functions, you need to add the power-management codes to the
+      driver. The additional codes for the power-management should be
+      <function>ifdef</function>'ed with
+      <constant>CONFIG_PM</constant>. 
+    </para>
+
+    <para>
+      ALSA provides the common power-management layer. Each card driver
+      needs to have only low-level suspend and resume callbacks.
+
+      <informalexample>
+        <programlisting>
+<![CDATA[
+  #ifdef CONFIG_PM
+  static int snd_my_suspend(snd_card_t *card, pm_message_t state)
+  {
+          .... // do things for suspsend
+          return 0;
+  }
+  static int snd_my_resume(snd_card_t *card)
+  {
+          .... // do things for suspsend
+          return 0;
+  }
+  #endif
+]]>
+        </programlisting>
+      </informalexample>
+    </para>
+
+    <para>
+      The scheme of the real suspend job is as following.
+
+      <orderedlist>
+        <listitem><para>Retrieve the chip data from pm_private_data field.</para></listitem>
+        <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</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>.</para></listitem>
+      </orderedlist>
+    </para>
+
+    <para>
+      A typical code would be like:
+
+      <informalexample>
+        <programlisting>
+<![CDATA[
+  static int mychip_suspend(snd_card_t *card, pm_message_t state)
+  {
+          /* (1) */
+          mychip_t *chip = card->pm_private_data;
+          /* (2) */
+          snd_pcm_suspend_all(chip->pcm);
+          /* (3) */
+          snd_mychip_save_registers(chip);
+          /* (4) */
+          snd_mychip_stop_hardware(chip);
+          /* (5) */
+          pci_disable_device(chip->pci);
+          return 0;
+  }
+]]>
+        </programlisting>
+      </informalexample>
+    </para>
+
+    <para>
+    The scheme of the real resume job is as following.
+
+    <orderedlist>
+    <listitem><para>Retrieve the chip data from pm_private_data field.</para></listitem>
+    <listitem><para>Enable the pci device again by calling
+    <function>pci_enable_device()</function>.</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>
+    </orderedlist>
+    </para>
+
+    <para>
+    A typical code would be like:
+
+      <informalexample>
+        <programlisting>
+<![CDATA[
+  static void mychip_resume(mychip_t *chip)
+  {
+          /* (1) */
+          mychip_t *chip = card->pm_private_data;
+          /* (2) */
+          pci_enable_device(chip->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);
+          return 0;
+  }
+]]>
+        </programlisting>
+      </informalexample>
+    </para>
+
+    <para>
+      OK, we have all callbacks now. Let's set up them now. In the
+      initialization of the card, add the following: 
+
+      <informalexample>
+        <programlisting>
+<![CDATA[
+  static int __devinit snd_mychip_probe(struct pci_dev *pci,
+                               const struct pci_device_id *pci_id)
+  {
+          ....
+          snd_card_t *card;
+          mychip_t *chip;
+          ....
+          snd_card_set_pm_callback(card, snd_my_suspend, snd_my_resume, chip);
+          ....
+  }
+]]>
+        </programlisting>
+      </informalexample>
+
+    Here you don't have to put ifdef CONFIG_PM around, since it's already
+    checked in the header and expanded to empty if not needed.
+    </para>
+
+    <para>
+      If you need a space for saving the registers, you'll need to
+    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,
+      This can be done by passing a macro SND_PCI_PM_CALLBACKS
+      in the pci_driver struct.  This macro is expanded to the correct
+      (global) callbacks if CONFIG_PM is set.
+
+      <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),
+          SND_PCI_PM_CALLBACKS
+  };
+]]>
+        </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 <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 ease of 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 wouldn't be so bad 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'll 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 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 alsa-kernel tree (to the corresponding directory,
+        such as <filename>alsa-kernel/pci</filename>) and eventually
+        integrated into 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 assumed:
+        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> like 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
+      <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_DETECT</constant> is set. Please note
+      that <constant>DEBUG_DETECT</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-assert">
+      <title><function>snd_assert()</function></title>
+      <para>
+        <function>snd_assert()</function> macro is similar with the
+      normal <function>assert()</function> macro. For example,  
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  snd_assert(pointer != NULL, return -EINVAL);
+]]>
+          </programlisting>
+        </informalexample>
+      </para>
+
+      <para>
+        The first argument is the expression to evaluate, and the
+      second argument is the action if it fails. When
+      <constant>CONFIG_SND_DEBUG</constant>, is set, it will show an
+      error message such as <computeroutput>BUG? (xxx) (called from
+      yyy)</computeroutput>. When no debug flag is set, this is
+      ignored. 
+      </para>
+    </section>
+
+    <section id="useful-functions-snd-runtime-check">
+      <title><function>snd_runtime_check()</function></title>
+      <para>
+        This macro is quite similar with
+      <function>snd_assert()</function>. Unlike
+      <function>snd_assert()</function>, the expression is always
+      evaluated regardless of
+      <constant>CONFIG_SND_DEBUG</constant>. When
+      <constant>CONFIG_SND_DEBUG</constant> is set, the macro will
+      show a message like <computeroutput>ERROR (xx) (called from
+      yyy)</computeroutput>. 
+      </para>
+    </section>
+
+    <section id="useful-functions-snd-bug">
+      <title><function>snd_BUG()</function></title>
+      <para>
+        It calls <function>snd_assert(0,)</function> -- that is, just
+      prints the error message at the point. It's useful to show that
+      a fatal error happens there. 
+      </para>
+    </section>
+  </chapter>
+
+
+<!-- ****************************************************** -->
+<!-- Acknowledgments  -->
+<!-- ****************************************************** -->
+  <chapter id="acknowledments">
+    <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 000000000000..ccda41b10f8a
--- /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 000000000000..5cb970612870
--- /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 continously
+
+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 seperately.
+
+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>
+Distributalbe under GPL.
diff --git a/Documentation/sound/alsa/OSS-Emulation.txt b/Documentation/sound/alsa/OSS-Emulation.txt
new file mode 100644
index 000000000000..ec2a02541d5b
--- /dev/null
+++ b/Documentation/sound/alsa/OSS-Emulation.txt
@@ -0,0 +1,297 @@
+                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.
+
+
+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.
+
+USB devices
+-----------
+Some USB devices support only 24bit format packed in 3bytes.  This
+format is not supported by OSS and no conversion is provided by kernel
+OSS emulation.  You can use the user-space OSS emulation via libaoss
+instead.
+
diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt
new file mode 100644
index 000000000000..25c5d648aef6
--- /dev/null
+++ b/Documentation/sound/alsa/Procfile.txt
@@ -0,0 +1,191 @@
+                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 (desribed 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
+
+
+Sequencer Information
+---------------------
+
+seq/drivers
+        Lists the currently available ALSA sequencer drivers.
+
+seq/clients
+        Shows the list of currently available sequencer clinets and
+        ports.  The connection status and the running status are shown
+        in this file, too.
+
+seq/queues
+        Lists the currently allocated/running sequener 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 reigster 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 000000000000..651adaf60473
--- /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 acticle 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 000000000000..1b0ac06ba95d
--- /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/hda_codec.txt b/Documentation/sound/alsa/hda_codec.txt
new file mode 100644
index 000000000000..e9d07b8f1acb
--- /dev/null
+++ b/Documentation/sound/alsa/hda_codec.txt
@@ -0,0 +1,299 @@
+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 *);
+};
+
+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 last, private_free callback, is optional.  It's called in the
+destructor to release any necessary data in the lowlevel driver.
+
+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(snd_card_t *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 list_head *p;
+        struct hda_codec *codec;
+        list_for_each(p, &bus->codec_list) {
+                codec = list_entry(p, struct hda_codec, 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_codec_read() and snd_codec_write().
+snd_hda_param_read() is for reading parameters.
+For writing a sequence of verbs, use snd_hda_sequence_write().
+
+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,
+                    snd_pcm_substream_t *substream);
+        int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec,
+                     snd_pcm_substream_t *substream);
+        int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec,
+                       unsigned int stream_tag, unsigned int format,
+                       snd_pcm_substream_t *substream);
+        int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec,
+                       snd_pcm_substream_t *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
+        };
+
+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.
+
+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.  In the patch resume callback, call
+snd_hda_resume_spdif().
+
+
+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 table with struct
+hda_board_config 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 snd_kcontrol_new_t.  The same array
+can be passed to snd_hda_resume_ctls() for resume.
+Note that this will call control->put callback of these entries.  So,
+put callback should check codec->in_resume and force to restore the
+given value if it's non-zero even if the value is identical with the
+cached value.
+
+Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be
+used for the entry of snd_kcontrol_new_t.
+
+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/seq_oss.html b/Documentation/sound/alsa/seq_oss.html
new file mode 100644
index 000000000000..d9776cf60c07
--- /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 000000000000..c1919559d509
--- /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.