Advanced Linux Sound Architecture - Driver
		==========================================
			    Installation guide


The ALSA driver replaces the OSS/Free driver.  Since version 0.4.0,
ALSA has supported only 2.2 or later kernels. The 2.0 kernels are no
longer supported.

You must compile the kernel with sound support (CONFIG_SOUND on
2.2/2.4 kernels) either as module or built-in.  You do not need to
select any of the other sound modules apart from sound support.

Before installing this driver, it will be helpful to read carefully
the documentation for insmod, modprobe, kmod and for the isapnp
module if you have an ISA PnP soundcard.


Module option name change after 0.9.0rc3
========================================

Note that module option names were changed in 0.9.0rc4. The 'snd_' prefix
was removed. You may use script in utils directory (module-options) to
convert your older /etc/modules.conf to newer one.


Quick install
=============

1) You must have full configured source for the Linux kernel which you
   want to use for the ALSA drivers. Note that ALSA drivers are part
   of the kernel, so there is necessary to resolve all symbol dependencies
   between the used kernel and ALSA driver code. Partly installed kernels
   (for example from distributor makers) can be unuseable for this action.

2) You must turn on sound support (soundcore module).

3) Run './configure' script.

 * General Options
   If you do not want ISA PnP support, use --with-isapnp=no switch.
   If you do not want sequencer support, use --with-sequencer=no switch.
   If you do not want OSS/Free emulation, use --with-oss=no switch.
   If you have udev or devfs and want to use more than eight cards, use
   --enable-dynamic-minors switch.
   If you want to turn on debug mode, use --with-debug=full switch.
   If you want to debug soundcard detection, try --with-debug=detect switch.

 * Kernel Source Tree
   On 2.4/2.6 kernels, the location of the kernel source tree is
   parsed automatilly from the running kernel.
   If it's not in the standard place, specify the path via
   --with-kernel=<kernel_directory>. 
   On 2.6 kernels, the build directory has to be given via
   --with-build=<kernel_build_dir> option additionally, too.

 * Drivers to Compile
   The card drivers to be compiled can be selected via --with-cards option.
   Pass the card driver name without "snd-" prefix.  To specify
   multiple drivers, list names with comma (,).
   Passing "all" will compile all possible drivers (and this is the
   default choice).
   Some drivers have compile options.  They can be passed via
   --with-card-options option.  Multiple options can be passed with comma,
   too.  The default is "all".
   For available cards and options, see ./configure --help.

 * Example
      ./configure --with-debug=full
      ./configure --with-cards=sb16,emu10k1 --with-card-options=sb16-csp

4) Run 'make'.

5) Run 'make install' as root.
   If you have already a system with ALSA init script, you should install
   just only modules via 'make install-modules' so that the existing init
   script won't be replaced.

6) Run the './snddevices' script to create new sound devices in /dev directory.
   Skip this step, if you have already /dev/snd/* files, or if you're
   using a DEVFS or udev.

7) Edit your kernel module config (either /etc/modprobe.conf or
   /etc/modules.conf, depending on the kernel version). If you are not
   sure, what to do, you may try the alsaconf script available in
   the alsa-utils package.

8) Run 'modprobe snd-xxxx' where xxxx is the name of your card.
   Note: All ALSA ISA drivers support ISA PnP natively, so you don't need
         isapnptools any more.  Don't use both together.  It will
         conflict.  For disabling the ALSA ISA PnP support, specify
         --with-isapnp=no configure switch.

You can also look at the utils/alsasound file. This script is designed for
the RedHat distribution, but it can be used with other distributions which
use System V style rc init scripts.

Note: All mixer channels are muted by default. You must use a native
      or OSS mixer program to unmute appropriate channels (for example a
      mixer from the alsa-utils package).

Note: This document notices the /etc/modules.conf file. Many current
      distributions uses the old /etc/conf.modules file. Both names are
      valid.


Kernel Module Configurations
============================

See alsa-kernel/Documentation/ALSA-Configuration.txt
(or Documentation/sounds/alsa/ALSA-Configuration.txt in linux-2.6
 kernel tree).


Driver cannot be activated?
===========================

1) You can check your soundcard setup again and read this install file
   (module parameters) carefully.
2) If you have got ISA PnP soundcard:
   native ISA PnP support: is your setup in /proc/isapnp correct?
3) If you have *non*-ISA PnP card:
   set isapnp=0 module option?  Otherwise the driver probes only the
   ISA PnP cards.
3) The driver is not still working: remake driver with:
     ./configure --with-debug=detect; make clean; make
   Reinsert new driver modules to kernel and look to /var/log/messages if
   there are some messages. If these messages do not help you, please
   create a new ticket in our bug reporting system.


Compilation from HG sources
===========================

You need GNU packages autoconf and automake installed in your system
to compile HG (Mercurial) sources of alsa-driver package.

For compilation you can use these commands:

	make ALSAKERNELDIR=../alsa-kernel all-deps
		(if the alsa-kernel-dir is really there)
	aclocal
	autoconf
	./configure
	make dep
	make

The included hgcompile script does this job for you.

Note: Some automake packages have missing aclocal program. Use newer version
      in the case.


Cross-compiling
===============

Use '--with-cross=prefix' parameter for the configure script.

Example:
  './configure --with-cross=arm-linux- --with-kernel=/home/ipaq/kernel/linux'.

For 2.6 kernels, pass the same kernel path to --with-build option, too. 


Autoloading on 2.2/2.4 Kernels
==============================

On 2.2 or 2.4 kernels, you have to set the additional aliases for
auto-loading via kmod in /etc/modules.conf:

----- /etc/modules.conf
# ALSA portion
alias char-major-116 snd
# OSS/Free portion
alias char-major-14 soundcore
alias sound-service-0-0 snd-mixer-oss
alias sound-service-0-1 snd-seq-oss
alias sound-service-0-3 snd-pcm-oss
alias sound-service-0-8 snd-seq-oss
alias sound-service-0-12 snd-pcm-oss
----- /etc/modules.conf

The aliases sound-service-x-y define the add-on modules for ALSA
OSS emulation.  For the second or later card, define more aliases
for mixer and pcm in addition, such as:

----- /etc/modules.conf
# OSS/Free portion - card #2
alias sound-service-1-0 snd-mixer-oss
alias sound-service-1-3 snd-pcm-oss
alias sound-service-1-12 snd-pcm-oss
----- /etc/modules.conf

You don't need to define service 1 and 8 for the second or later
cards.

If you want to autoclean your modules, you should put below line to your
/etc/crontab:

*/10 * * * *   root  /sbin/modprobe -rs snd-card-0 snd-card-1; /sbin/rmmod -as

You may also want to extend the soundcard list to follow your requirements.


Information about Additional Modules
====================================

  Module snd-msnd-pinnacle
  ------------------------

    Module for Turtle Beach MultiSound Pinnacle/Fiji soundcards.

    io		- Port # for pinnacle/fiji card
    irq		- IRQ # for pinnalce/fiji card
    mem		- Memory address (0xb0000, 0xc8000, 0xd0000, 0xd8000,
		  0xe0000 or 0xe8000)
    write_ndelay - enable write ndelay
    calibrate_signal - calibrate signal (?)

    Module supports only one card.

  Module snd-pdplus
  -----------------

    Module for Sek'D/Marian Prodif Plus soundcards.

    silent_exit	- Do not reset when driver is unloaded.
    init_adat	- Initialise the card in ADAT mode (instead of in digital stereo).

    This module supports multiple cards.

  Module snd-serialmidi
  ---------------------

    Module for generic serial MIDI adapters.

    sdev	- Device file string for serial device
		  (default = "/dev/ttyS0")
    speed	- Speed in bauds. (9600,19200,38400,57600,115200)
		  (default = 38400)
    adaptor	- Type of adaptor.
                  0 = Soundcanvas, 1 = MS-124T, 2 = MS-124W S/A,
		  3 = MS-124W M/B
    devices	- Number of devices assigned to the card.  Default is 1.
  		  When this is more than 1, multiple serial devices (up
		  to 8) are assigned to a single card.  The number of
		  the tail of the device file name is increased for
		  each device.
    handshake	- Enable/disable handshaking (default = 1)	

    This module supports multiple devices.

  Module snd-asihpi
  -----------------

    Module for AudioScience ASI soundcards

    This module supports multiple cards.
    The driver requires the firmware loader support on kernel.

  Module snd-pcsp
  ---------------

    Module for PC-Speaker driver.

    For X86 only.  The kernel patch is required in advance, found in
    utils/patches/pcsp-kernel-2.6.10-03.diff


Trouble Shooting
================

Unresolved symbol with RedHat 9
-------------------------------

Run depmod -ae and check which symbol is missing.
If the unresolved symbol is "schedule_work", this is because RedHat
shipped the kernel with incomplete implementation of workqueue.
For solving this problem, run the following on the top of alsa-driver
directory:

	% touch include/linux/workqueue.h

and run "make clean", "make" again.