alsa howto

[Gene Collins]

Hi all.  In view of some of the questions about using the alsa drivers
that have been showing up on the list, I thought I'd post my alsa howto
here.  You can get the text file from linux-speakup.org in the
pub/linux/goodies directory.  It's called alsa-howto.txt.  This does not
apply if you are running the 2.6.0-testing kernels, since you can build
alsa directly into the kernel, and not have to deal with modules at all.
 I hope some of you will find this useful.

Gene

---cut-here---
A Twelve step guide to installing the ALSA drivers
by Gene Collins (collins at iastate.edu)
Last modified: Mon Sep 22 09:20:23 2003

This is a mini-how-to on how to get and install the ALSA (Advanced Linux
sound architecture) drivers.  This how-to is copyrighted by Gene Collins,
1999-2003, and is distributed under the GNU Public License version 2 or
later.  You are granted all rights to this document specified under
version 2 or later of the GNU Public License.  For further information
on copying this document, see the COPYING file in the
alsa-driver-(version-number) directory, after you download the drivers. 
If you make any changes, please notify me, Gene Collins, by sending
email to collins at iastate.edu.

This document comes with absolutely no warranty, either express or
implied.  If your equipment is damaged, or something doesn't work after
you follow these instructions, neither the author, nor anyone else is
liable for any damages.  You get to keep all the pieces (grin).

The official home page for the ALSA drivers is:

http://www.alsa-project.org/

The ALSA files on the speakup site are * NOT * guaranteed to be up to
date, and in fact, are probably very old.  This document is not updated
very often and so may become out of date.  You should use common sense
and consult the ALSA web site for the latest versions of the drivers,
libraries and utilities.  Also, the configuration files on the speakup
site are very old, and should not be used with the newer versions of the
drivers.

In this document, the expression (version-number) is used as a place
holder to represent the version number of the actual drivers, libraries
and utilities you will be working with.  These change very frequently,
and it is not possible to keep this document up to date with the latest
version numbers.

You will need to download the following files:

alsa-driver-(version-number).tar.gz

alsa-lib-(version-number).tar.gz

alsa-utils-(version-number).tar.gz

After you have downloaded the above mentioned files, do the following:

1.  Move the files you have downloaded into an appropriate directory. 
This can either be your home directory, or your /usr/src directory, for
example.  Untar the .gz files with the following command:

tar xzvf alsa*gz

This should create three directories under the directory that contains
the tar.gz files.  These directories are:

alsa-driver-(version-number)

alsa-lib-(version-number)

alsa-utils-(version-number)

Note, the directory names will reflect the version
number of the package you downloaded.

2.  If you haven't downloaded any kernel source code, you will need to
do so.  You can get kernel sources from ftp.kernel.org.  In the U.S.,
you can use ftp.us.kernel.org.  Check the ALSA documentation to see
which version of the kernel the drivers you downloaded will work with. 
Remember that kernel versions with an odd second number are development
kernels.  For example, versions 2.1.x and 2.3.x are development kernels,
while versions 2.0.x and 2.2.x are production kernels.  The number
represented by x can be any number.  It is the second number that
determines whether a kernel version is production or development.

Once you have the kernel sources downloaded, untar them under your
/usr/src directory.  This should create a /usr/src/linux directory. 
After you have unpacked the sources, change to the /usr/src/linux
directory, and configure the kernel.  If you don't know how to
configure, compile and install your kernel sources, see the README file
in the /usr/src/linux directory.  Note that the README file name really
is in upper case letters.  When you are configuring the kernel, answer
yes to the sound card option, but no to all of the sound card driver questions. 

Note that newer versions of the kernel sources, ie. 2.4.20, 2.4.21, etc.
create directories with the version number of the source as a part of
the directory name, for example linux-2.4.21.  You can use the command
ln -s /usr/src/directory-name linux to create a symbolic link named
linux, which will point to your actual source directory.  See the man
page for ln, if you need more information on how to use it.

The ALSA drivers are installed as modules, and will not work if you have
some other sound driver loaded.  After you have configured your kernel
source, issue the make dep, make bzImage, and make install commands
discussed in the /usr/src/linux/README file.  After you have configured,
compiled and installed your kernel, you should reboot, before
configuring, compiling and installing the ALSA drivers.

3.  Change to the alsa-driver-(version-number) directory, and give the following
commands:

./configure

Note that if the ./configure command complains about not having g++, you
will need to download it and install it before proceeding to the next
command.  You will also have to rerun ./configure after installing g++. 
Consult the documentation for your distribution of Linux, to find out
how to download and install software for your distribution of Linux.  If
you have Linux on a cdrom, check there first.

You can configure ALSA to work with only one or 2 sound cards if you
like, instead of for all available sound cards.  The reason for doing
this is to save disk space by not compiling and installing a lot of
drivers for cards you don't have, and which will thus never be used. 
You can do that like this:

./configure --with-cards="sb16"

You can substitute the name of your card for the sb16 card listed above.
 With newer versions of alsa, you can specify a list of cards separated
by spaces.  Type ./configure --help | more to see a list of all
configuration options.

make

You can redirect the output of the make command to a file as follows:

make >makelog 2>&1 &

The above command will redirect all output, including any error messages
to a file called makelog, and run the make process in the background. 
You should let the make process complete before proceeding to the next
step.  You can use the jobs command of the shell, if you are running
bash or tcsh, to find out whether the make job is still running. 
Pressing return at the shell prompt will also tell you whether the job
is finished.  You can also type set -b at the shell prompt if you are
using the bash shell, and you will be notified automatically when the
job completes.  If the job completes successfully, the job will exit
with a done message, but if there are errors, make will exit with an
exit message.  If this happens, you should read through the makelog file
to find the  errors.
 
4.  Either log on as root or su to root.  Once you are the root user, cd
to the alsa-driver-(version-number) directory, if you aren't already
there.  Then give the command:

make install

If all goes well, your drivers will be installed in
/lib/modules/<kernel-version-number>/misc.  <kernel-version-number> is
the version number of the kernel you are currently running.  For
example:

/lib/modules/2.2.10/misc

Note:  The exact directory where the modules are installed varies
depending on which version of the ALSA drivers you are working with, as
well as the version number of the kernel you are using.

5.  Repeat steps 3 and 4 for the alsa-lib-(version-number) directory
and the alsa-utils-(version-number) directory.  That is, change to each
of these directories and give the commands:

./configure

make

make install

Be sure you are the root user before issuing the make install command.

6.  You will need to append some lines to your aliases file if you are
running Redhat.  If you are running Debian, you can just create a file
called ALSA in /etc/modutils.  The lines you need depend on which sound
card or cards you are using.  Look at the INSTALL file that comes with
the alsa-drivers source.  Note that INSTALL is in all uppercase.  Here is
an example of my /etc/alsa file on a machine using an intel8x0 and an
sblive card.

# ALSA native device support
alias char-major-116 snd
options snd major=116 cards_limit=2

alias  card-0  emu10k1
options  emu10k1 snd_index=1 snd_id="sblive!" \
	buffer_size=8

alias snd-card-1 snd-intel8x0
options snd-intel8x0 index=0 id="Intel 8x0" 

# OSS/Free setup
alias char-major-14 soundcore
alias sound-slot-0  card-0
alias sound-service-0-0  mixer-oss
alias sound-service-0-1  seq-oss
alias sound-service-0-3  pcm-oss
alias sound-service-0-8  seq-oss
alias sound-service-0-12  pcm-oss
alias sound-slot-1  card-1
alias sound-service-1-0  mixer-oss
alias sound-service-1-1  seq-oss
alias sound-service-1-3  pcm-oss
alias sound-service-1-8  seq-oss
alias sound-service-1-12  pcm-oss

If you are running Slackware, you will have to add lines similar to the
above in your modules.conf file.  Remember that the lines above are an
example, and will probably not work on your system.  Read the INSTALL
file for examples of what to enter for your specific card.

7.  if you are running Debian or Redhat Linux, run the update-modules
command.

8.  Change back to the alsa-driver-(version-number) directory.  Make
sure you are logged on as root.  Give the command:

./snddevices

This command runs a script that will insure that you have the proper
devices for the ALSA drivers in your /dev directory.

9.  To insure that you can access the audio devices as your normal user
id, edit your /etc/group file, and add your user-id to the audio group. 
Just find the line that contains the word audio, move to the end of the
line, and then type your user-id.  If you want to add more than one
user-id, separate the user-ids with commas.  Then save the file. 
Remember to log out and then log back in after you add yourself to the
audio group.

10.  Look in your /etc directory.  If you have a file called
modules.conf, change to the /etc/init.d directory.  Look for a file
called alsasound, and edit it.  change the reference to conf.modules to
modules.conf and save the file.  If you had a conf.modules file in your
/etc directory, and not a modules.conf, then ignore this step.

11.  If you did not reboot after configuring and installing your kernel,
do so now.  You should see a message in your start up messages that
says, "starting ALSA sound drivers."  after logging on as root, give the
command:

lsmod

If you see a list of sound modules along with any other modules you have
loaded, your ALSA drivers are properly loaded.  give the command:

amixer groups

to display a list of the available mixer groups you have available.  You
can type:

amixer get 'group-name'

to see the values a particular group is set to.  The group name must be
in single quotes, and typed in exactly the combination of upper and
lower case characters shown for each group name.  For more information
on amixer, see the man pages.

12.  When you first install the ALSA drivers, your mixer settings are
all set to 0 by default.  This means you will have to set and unmute the
controls you need.  This can be most easily accomplished by using the
alsamixer utility.  Just use the left and right arrow keys to move among
the various controls.  The up and down arrows, page up and page down
will set the level of each control.  Pressing the m key will toggle the
mute state of the control.  Pressing the space bar will cause a control
to be captured.  See the man page for ALSA mixer for more information on
its use.

You can also use amixer, which is a command line type mixer utility to
set your mixer controls.  Again, see the man page for amixer for more
information on its use.

You can also use the aumix command with the ALSA drivers.  To see what
your settings are, type:

aumix -q

This will show the settings that aumix knows about.  For more
information on using aumix, see the man pages. After you have adjusted
your mixer settings to your satisfaction, you must save them with the
command:

alsactl store

The alsactl command is only in your path when you are logged on as root.

You should now be ready for the acid test.  Try playing a wav file or a
cd.  

Please note that I am * NOT * the author of the ALSA drivers, but only
the author of this mini how to.  If you have questions about the steps
in this how-to, send them to collins at iastate.edu.  You can try sending
alsa driver installation questions to the speakup list at
speakup at braille.uwo.ca.  For bug reporting, see the alsa-project site
listed above.  Enjoy.