root/drivers/sound/Readme.linux

/* */

Installation
------------

IMPORTANT!      Read this if you are installing a separately
                distributed version of this driver.
                Check that your kernel version works with this
                release of the driver (see Readme). Also verify
                that your current kernel version doesn't have more
                recent sound driver version than this one.

- Since you are reading this, you have already installed the files so
  let's skip this step. To be serious, the sound driver belongs
  to linux/drivers/sound. 

- To build the device files you need to run the enclosed shell scrip 
  (see below).

- If you are installing a separately distributed version, copy the
  soundcard.h to /usr/include/linux. It may contain some new stuff.

- Copy the sound/ultrasound.h  to /usr/include/sys
  (Remove the old one from /usr/include/sys /usr/include/linux first).

- Ensure you have the following symlink:
  ln -s /usr/include/linux/soundcard.h /usr/include/sys/soundcard.h

- Configure and compile Linux as normally (remember to include the
  sound support during "make config").

Boot time configuration (using lilo and insmod) 
-----------------------------------------------

NOTE!   This information is little bit obsolete since it doesn't cover
        some cards recently added to the driver. The following text
        describes parameters just for some older cards. In addition
        this method will not work with cards which have more than one
        DMA channel or if the driver number is bigger than 15. (Driver
        numbers are defined in soundcard.h).

-------------------------------------------------------------------
NOTE2!  This method to configure the sound driver is not normally
        required. All configuration information is entered when the
        kernel/driver is compiled. This method just gives a way
        to override some configuration parameters during boot.

        So THE METHOD PRESENTED IN THIS CHAPTER IS NORMALLY COMPLETELY
        USELESS. DON'T USE IT UNLESS YOU HAVE A VERY SPECIAL REASON TO
        DO THAT.

        !!!!!!!!!!!!!!!!!!!! PLEASE NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!!!
        !!! Finding a working sound= command line is a difficult   !!!
        !!! and timeconsuming task. For this reason I will not     !!!
        !!! answer to messages asking about how to do it. So       !!!
        !!! please don't use this method if you have any problems  !!!
        !!! with it.                                               !!!
        !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

-------------------------------------------------------------------

This version of the sound driver has capability to accept the configuration
parameters from the boot loader (for example lilo). By default the 
driver is booted using the parameters given before compiling the driver
('make config' or 'make soundconf'). If the kernel is booted using lilo and
the boot command is given manually, it's possible to give the configuration
parameters on the command line. Just hold down the <Alt> key when lilo
starts. Then give the boot command manually and append a sound= argument
to the boot command line. For example:

lilo boot: linux sound=0x222071,0x138800

The sound= argument could contain several configuration entries separated by a
comma. Each option gives the configuration for one sound device.
Give the options in the order given below. Other order of use is undefined.
Each option is encoded as the following:

        0xTaaaId, where
          ||  ||
          ||  |+----   d = DMA channel (0, 1, 3, 5, 6 or 7)
          ||  +-----   I = IRQ (HEXADECIMAL!!! 1=1, ..., 9=9, 10=a, ..., 15=f)
          |+-------- aaa = I/O address (hexadecimal)
          +----------  T = device type  1=FM Synth (YM3812 or OPL3)
                                        2=SoundBlaster (1.0 to 2.0, Pro, 16)
                                        3=ProAudioSpectrum16
                                        4=Gravis UltraSound
                                        5=MPU-401 UART midi
                                        6=SB16 (16 bit DMA number)
                                        7=SB16 Midi (MPU-401 emulation)
                        (There are some new ones also but they are currently
                        not documented. The card numbers are in soundcard.h).

These are the configuration templates for various soundcards:

        0)      Disable the sound driver
                
                sound=0

        1)      AdLib

                sound=0x138800

        2)      SoundBlaster family and compatibles

                sound=0x2220Id,0x138800   (remember to set the IRQ and DMA)
        or if you have SB16 or SB16ASP, you have to use the following:
                (use the same IRQ (the I colums) in all three places. The
                 the D is the 16 bit DMA channel (5 to 7) and the d is 
                 the 8 bit one (1 or 3). The X is the 2nd digit of the
                 midi IO address (3 or 0)).
                sound=0x2220Id,0x6220ID,0x73X0I0,0x138800

        3)      ProAudioSpectrum16, ProAudioStudio16, Logitech Soundman16 etc.

                sound=0x3388Id,0x2220Id,0x138800 (set the DMAs and IRQs)
         
        4)      Gravis UltraSound

                sound=0x42X0Id  (X is 1, 2, 3 or 4. Set the DMA and IRQ)
        
        5)      MPU-401

                sound=0x5aaaI0

If you have more than one soundcards, you have to concatenate the options
for each of the cards. There cannot be more than one sound= argument in the
command line. For example use "sound=0x5aaaI0,0x138800" if you have AdLib
and MPU-401 on your system. 
If there are two or more sound= arguments
in the boot command line, just the last one takes effect. The earlier ones
will be ignored silently.

The boot time configuration feature is intended mainly for distributors of
precompiled kernels. When this feature is used, drivers for all of the
cards have to be enabled before compiling the driver. The configurator program
doesn't enable MPU-401 when the full driver option is selected. It must be
enabled by uncommenting "#define EXCLUDE_MPU401" in the sound/local.h.

Important note!

The sound driver is enabled by default. If the kernel is booted without
using the sound=0 option, the sound driver is initialized using the compile
time parameters. This could be dangerous (specially if the MPU-401 driver
is enabled with I/O address 0x330 (used by AHA-1542 also)). If you want to
compile the driver to be inactive by default, you have to append a
#define SND_DEFAULT_ENABLE      0
to the sound/local.h before compiling the driver.

Remember to check that the sound setup routine is included in the 
bootparams structure in linux/init/main.c. It should contain the following
lines:

#ifdef CONFIG_SOUND
        { "sound=", sound_setup },
#endif

In case these lines were not there, you have to insert them (the driver works
without them but it's not possible to give the boot time parameters for the
sound driver). Add also the following line somewhere near the beginning of
linux/init/main.c:

extern void sound_setup(char *str, int *ints);

Problems
--------

If you have any kind of problems, there is a debugging feature which
could help you to solve the problem. To use it, just execute the
command:

        cat /dev/sndstat 

and look at the output. It should display some usefull info about the
driver configuration. If there is no /dev/sndstat 
(/dev/sndstat: No such file or directory), ensure that you have executed the
soundinstall script (at the end of this file). The message: 
/dev/dsp: No such device means that you don't have the sound driver installed
on your kernel or the driver version is earlier than 1.99.6.


- /dev/???????: No such file or directory.
Run the script at the end of this file.

- /dev/???????: No such device.
You have not booted with a kernel containing the driver or the I/O address
configuration doesn't match your hardaware. 

- The module player (str) plays just a second and then stops completely.
You have incorrect IRQ settings (usual with SB cards).

- There is pauses in the playback of the module player (str).
The str program requires more than 40% of the speed of a 486/50 to play
without pauses at 44 kHz speed. A 386/25 can hardly play faster than 22 kHz.
You should use lower speed (-s speed), buy a faster computer or a Gravis 
UltraSound card. (If you already have GUS, you should use gmod and not the
str). If the DSP_BUFFSIZE in the sound/local.h is less than (nr_channels*
speed_in_Hz * (bits/8))/2, it could explain the pausing problem. Also check
that the turbo swich is on and don't run applications like weather forecasting
on background. Sometimes (very rarely) an IRQ conflict can cause similar
problems with SB cards.
If you want to play modules on a 386sx while recompiling the world, buy a GUS.
It runs without burning your CPU.

Hannu Savolainen
hannu@voxware.pp.fi

----------------- cut here ------------------------------
#!/bin/sh
#
#       soudinstall             
#
#
# Create the devices
#
#       Mixer devices
#
if [ -e /dev/mixer ]; then 
        rm -f /dev/mixer 
fi
 
mknod -m 666 /dev/mixer c 14 0
if [ -e /dev/mixer1 ]; then 
        rm -f /dev/mixer1 
fi
mknod -m 666 /dev/mixer1 c 14 16


#       Sequencer       (14, 1)
#
if [ -e /dev/sequencer ]; then
        rm -f /dev/sequencer
fi
mknod -m 666 /dev/sequencer c 14 1

if [ -e /dev/patmgr0 ]; then
        rm -f /dev/patmgr0
fi
mknod -m 666 /dev/patmgr0 c 14 17
if [ -e /dev/patmgr1 ]; then
        rm -f /dev/patmgr1
fi
mknod -m 666 /dev/patmgr1 c 14 33

        #       music   (14, 8)
        #
        if [ -e /dev/music ]; then
                rm -f /dev/music
        fi

        mknod -m 666 /dev/music c 14 8
        if [ -e /dev/sequencer2 ]; then
                rm -f /dev/sequencer2
        fi
        ln -s /dev/music /dev/sequencer2

#       Midi devices
#
if [ -e /dev/midi ]; then
        rm -f /dev/midi         # Old name. Don't use it
fi
        if [ -e /dev/midi00 ]; then
                rm -f /dev/midi00
        fi
        mknod -m 666 /dev/midi00 c 14 2
        
        if [ -e /dev/midi01 ]; then
                rm -f /dev/midi01
        fi
        mknod -m 666 /dev/midi01 c 14 18
        
        if [ -e /dev/midi02 ]; then
                rm -f /dev/midi02
        fi
        mknod -m 666 /dev/midi02 c 14 34
        
        if [ -e /dev/midi03 ]; then
                rm -f /dev/midi03
        fi
        mknod -m 666 /dev/midi03 c 14 50
#
#       DSP             (14, 3)
#
if [ -e /dev/dsp ]; then
        rm -f /dev/dsp
fi
if [ -e /dev/dsp0 ]; then
        rm -f /dev/dsp0
fi
mknod -m 666 /dev/dsp0 c 14 3
ln -s /dev/dsp0 /dev/dsp

#
#       SPARC compatible /dev/audio     (14, 4) 
#
if [ -e /dev/audio ]; then
        rm -f /dev/audio
fi
if [ -e /dev/audio0 ]; then
        rm -f /dev/audio0
fi
mknod -m 666 /dev/audio0 c 14 4
ln -s /dev/audio0 /dev/audio

#
#       DSP1            (14, 19) /dev/dsp for the second soundcard.
#                               Also the SB emulation part of the
#                               PAS16 card.
#
if [ -e /dev/dsp1 ]; then
        rm -f /dev/dsp1
fi
mknod -m 666 /dev/dsp1 c 14 19
#
#       SPARC audio1    (14, 20) 
#                               /dev/audio for the second soundcard.
#                               Also the SB emulation part of the
#                               PAS16 card.
#
if [ -e /dev/audio1 ]; then
        rm -f /dev/audio1
fi
mknod -m 666 /dev/audio1 c 14 20
#
#       /dev/sndstat    (14,6)  For debugging purposes
#
if [ -e /dev/sndstat ]; then
        rm -f /dev/sndstat
fi
mknod -m 666 /dev/sndstat c 14 6
exit 0

/* */