INSTALL

		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".

   The integer options can be also passesd in a form of X=Y like
   "hda-prealloc-size=1024".
   For available cards and options, see ./configure --help.

   Note that you have to specify all items you want to enable unless
   you pass "all".  Or, pass "all" and additionally "NAME=n".  This will
   enable all but the ones that with =n suffix.  See examples below.

 * Module installation path
   By passing --with-moddir, you can specify the path to install
   modules.  When an absolute path is given, the modules are installed
   to the given directory.  When a relative path is given,
   e.g. --with-moddir=updates, the modules will be installed to
   /lib/modules/$VERSION/updates directory.  The directory name might
   depend on distributions, but in general, "updates" should work.

   Note that when no moddir option is given, the newly built modules
   will _replace_ the existing modules in
   /lib/modules/$VERSION/kernel/sound. 
   So, if you want to keep the original binaries, better to use
   --with-moddir=updates.

 * Example
      ./configure --with-debug=full
          Enable debug option "full"

      ./configure --with-cards=sb16,emu10k1 --with-card-options=sb16-csp
          Build for cards sb16 and emu10k1 drivers and enable sb16-csp
          option.  But all other card options are *disabled*.

      ./configure --with-cards=all,hda-intel=n
          Build drivers except for hda-intel.

 * Tips
  - You shouldn't try to save the build time too much.  Better to
    avoid to pass --with-cards and especially --with-card-options
    options unless you really know what you are doing.  Depending
    on the combination of options, you can screw up the build pretty
    easily!

  - The --withdebug=full option is in general recommended.

  - On modern distros with 2.6 kernel, you are likely using udev.
    Don't forget to add --enable-dynamic-minors option.  Otherwise a
    device-file mismatch might happen.

  - In short, a safe combination for the recent distros is:
	./configure --with-debug=full --enable-dynamic-minors \
		--with-moddir=updates

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).
   The recent distros don't need special setups (except for some ISA
   or static drivers), so you can skip this.
   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 GIT sources
============================

You need GNU packages autoconf and automake installed in your system
to compile GIT 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 gitcompile script does this job for you. The ALSAKERNELDIR
can be eighter alsa-kmirror tree or whole Linux 2.6 source tree (see
"Compilation from Linux kernel tree").

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


Compilation from Linux kernel tree
==================================

If you have a complete Linux kernel tree, you can build the ALSA drivers from
that kernel tree instead of from an alsa-kernel tree.  Note that the ALSA
version included in that kernel tree must match the ALSA version of this 
alsa-driver-build tree.  The ALSA modules built from the kernel tree will be
built for the current running kernel, and not for the kernel version or
configuration in the kernel tree.  In other words, the currently running
kernel version and the kernel version in the kernel tree need not be
identical.

Two ways are available:

Use gitcompile script directly:
-------------------------------

	ALSAKERNELDIR=<YOUR-LINUX-KERNEL-TREE-PATH> ./gitcompile

Use utils/setup-alsa-kernel script:
-----------------------------------

In this case, run utils/setup-alsa-kernel script in alsa-driver directory:

	utils/setup-alsa-kernel YOUR-LINUX-KERNEL-TREE-PATH

This script will create alsa-kernel sub-directory and make necessary symlinks
automatically.  If you would like to copy the files instead of creating
symlinks (e.g. make an alsa-driver tarball), pass the -c option to
setup-alsa-kernel:

	utils/setup-alsa-kernel -c YOUR-LINUX-KERNEL-TREE-PATH

After that, run the gitcompile script.


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.


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).

When DEVFS is enabled, snd module has the following option:

    device_mode
		- permission mask for dynamic sound device filesystem
		- This is available only when DEVFS is enabled
		- Default: 0666
		- E.g.: device_mode=0660


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

  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.


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.