Release notes for the Linux Sound Driver 2.2b
-----------------------------------------------

This version is just version 2.0 with some kind of SB16
support. The SB16 works now in 8 bit mono mode up to speed
44100 Hz. Stereo recording and playback is not supported with
the SB16 yet. Also the 16 bit mode is missing.
In addition this has capability to read the configuration
parameters at boot time (only in the Linux version - See linux/Readme).

You will need the snd-util-2.0.tar.gz and snd-data-0.1.tar.Z
packages to use this driver. They should be in the same
ftp site or BBS from where you got this driver. For
example at nic.funet.fi:pub/OS/Linux/*.

If you are looking for the installation instructions, please
look at linux/Readme.

Welcome to use the Gravis UltraSound driver for Linux. This
driver still supports the same cards than version 1.0c 
(SoundBlaster, SB Pro, Pro Audio Spectrum 16 and AdLib). 
In addition there is rather limited support for MPU-401
(and compatible) midi cards. Also the OPL-3 synthesizer
of the SB Pro and PAS16 cards is now supported in the 4 OP
modes.
Most of the features of the /dev/sequencer device file are
available just for GUS owners. 

The SoundBlaster 16 and SB 16 ASP cards are now supported
but just in 8 bit mono mode (up to 44.1 kHz).

NOTE!	There are separate driver for CD-ROMS supported by
	some soundcards. The driver for CDU31A (Fusion 16) is
	called cdu31a-0.6.diff.z. It will be contained in the
	Linux version 0.99.12. The driver for the CD-ROM of SB Pro
	is sbpcd0.4.tar.gz (these were the latest versions when I wrote
	this). These files should be at least at sunsite.unc.edu.
	Also the SCSI interface of the PAS16 should be supported by
	Linux 0.99.13k and later.

	There is also a driver for joystick. Look for file joystick-0.5.tar.gz
	(sunsite).


Compatibility with the earlier versions
---------------------------------------

IMPORTANT!!!!!!!!!!!!!!!!!!!!!!

This version is not binary or source compatible with the version 1.0c.

The ioctl() interface has changed completely since version 1.0c. All
programs using this driver must be at least recompiled. 
The snd-util-2.0 package contains some utilities for this version.

The version 1.0c and earlier used a 'nonportable' ioctl calling scheme
where the input argument was passed by value and the output value was
returned as the functional return. For example setting the speed of
/dev/dsp were done as the following:

	int actual_speed;
	actual_speed = ioctl(fd, SOUND_PCM_WRITE_RATE, 44100);

After version 1.99.0 this must be done as the following:

	int actual_speed = 44100;
	ioctl(fd, SOUND_PCM_WRITE_RATE, &actual_speed);

If you have an application written for the version 1.0, you should search
for the strings SNDCTL_ and SOUND_ and to check the parameters. 
The following ioctl calls have changed:

	SNDCTL_SEQ_GETOUTCOUNT
	SNDCTL_SEQ_GETINCOUNT
	SNDCTL_SEQ_TESTMIDI
	SNDCTL_DSP_SPEED
	SNDCTL_DSP_STEREO
	SNDCTL_DSP_GETBLKSIZE
	SNDCTL_DSP_SAMPLESIZE
	SOUND_PCM_WRITE_CHANNELS
	SOUND_PCM_WRITE_FILTER
	SOUND_PCM_READ_RATE
	SOUND_PCM_READ_CHANNELS
	SOUND_PCM_READ_BITS
	SOUND_PCM_READ_FILTER
	SOUND_PCM_WRITE_BITS
	SOUND_PCM_WRITE_RATE
	SOUND_MIXER_READ_*	(several ones)
	SOUND_MIXER_WRITE_*	(several ones)

Since the this version will support more than one synthesizer devices
at the same time, the ioctl(SNDCTL_FM_LOAD_INSTR) is obsolete. In addition
there is some new fields which must be initialized. Look at the sbiset.c in
the snd-util-2.0 package for further info.

This version is almost 100% compatible with the alpha test version (1.99.9). The
difference is in the installation procedure.

Using the driver under other environments than Linux
----------------------------------------------------

**** There is some ISC and SCO stuff in this driver. Please stay away ****
This stuff is here just because I want to be in sync with the porters. This
ports don't work yet.
The ISC port is by Andy Warner (andy@harris.nl). 

There FreeBSD port is by 
There is a FreeBSD port by Jim Lowe (james@blatz.cs.uwm.edu) in the directory
freebsd. (Based on my 386bsd port which was in the previous release (1.99.9).
It's should work but it requires still some testing. It should work
with the NetBSD 0.9 also but propably not with the 386bsd 0.1.
There has been some problems with GUS in SCO and NetBSD.
In addition I'm preparing a SCO port myself. Yet again, these ports
are little incomplete and untested. It could be possible to get them to work
with finite amount of hacking but be careful. 

/dev/sndstat
------------

NOTE! This device file is available only for Linux at this time.

This is a new devicefile for debugging purposes. A better place for
it is in the /proc -directory but I was just too lazy to implement it
properly. The /dev/sndstat (major 14, minor 6) is a file which returns
info about the current configuration (see the example below). If you
send me a error/problem report, please include a printout from this 
device to your message (cat /dev/sndstat).

Note!	This device file is currently present only in the Linux version
	of this driver.

------ cut here --- cat /dev/sndstat example --------
Sound Driver:1.99.7 (Fri Jul 9 17:01:47 GMT 1993 root@lucifer.savolai.fi)
Config options: 0x00000d4b

Major number: 14
HW config: 
Type 4: Gravis Ultrasound  at 0x210 irq 15 drq 6
Type 3: ProAudioSpectrum  at 0x388 irq 10 drq 3
Type 2: SoundBlaster  at 0x220 irq 7 drq 1
Type 1: AdLib  at 0x388 irq 0 drq 0

PCM devices:
00: Gravis UltraSound
01: Pro Audio Spectrum
02: SoundBlaster 2.0

Synth devices:
00: Gravis UltraSound
01: Yamaha OPL-3

Midi devices:
00: Gravis UltraSound
01: Pro Audio Spectrum

Mixer(s) installed
------ cut here ---- End of Example -----------

Known bugs/limitations
----------------------

- It's not possible to open /dev/dsp (or /dev/audio) while the 
  /dev/sequencer is open for output and GUS is the only soundcard
  installed. It's possible if /dev/dsp is opened before /dev/sequencer
  but at this time the GUS is not available for access via /dev/sequencer.
  This is a limitation of the driver.
- MPU-401 driver hangs the computer on boot if there is no MPU-401 installed.
  It uses by default the I/O port 0x330 whic is used by Adaptec 1542 SCSI
  adapter.
- The /dev/sequencer playback to GUS sounds sometimes rather weird. Hitting
  ^C and playing again should solve this problem. This is propably caused by
  incompatibilities between GUS and certain VLB motherboards. Try to avoid
  switching between VTs while patches are being loaded to the GUS.
- There is a skeleton of the patch manager support. It don't work in
  this version. 


Future development
------------------

- The SB16 card should be fully supported some day. I have the SDK for it
  now so it should not take infinite time to implement it.
- Since this driver is no longer just the Linux Sound Driver, it's time
  to give it a new name. I have planned to use name VoxWare.
- I'm writing a Hacker's guide to the VoxWare sound driver. Should
  be ready within this(/next) year (alpha version).
- Completion of the ISC, SCO and BSD ports. Port to SVR4.2.
- I'm interested to implement/include support for new soundcards and 
  operating systems. 

  Hint for the soundcard and OS manufacturers:
  I'm collecting soundcards (high end ones) and SDKs for them. In
  addition I'm collecting PC operating systems. I will be happy if
  somebody sends me such items. In addition such kind of donation
  makes it easier to change the VoxWare driver to support your
  soundcard or operating system. However, please contact me before
  sending anything.

I will propably release some fix versions within this and next year. At
least when the non-Linux versions get ready. The next major release (3.0)
will be quite complete rewrite and released after about a year (end of 94 or
beginning of 95).


Contributors
------------

This driver contains code by several contributors. In addition several other
persons have given usefull suggestions. The following is a list of major
contributors. (I could have forgotten some names.)

	Craig Metz	1/2 of the PAS16 Mixer and PCM support
	Rob Hooft	Volume computation algorithm for the FM synth.
	Mika Liljeberg	uLaw encoding and decoding routines
	Greg Lee	Volume computation algorithm for the GUS and
			lot's of valuable suggestions.
	Andy Warner	ISC port
	Jim Lowe	FreeBSD port

Regards,

Hannu Savolainen
hsavolai@cs.helsinki.fi

Snail mail:	Hannu Savolainen
		Pallaksentie 4 A 2
		00970 Helsinki
		Finland

---------- linux/Readme:

Sound Card Driver version 2.2

This directory contains the driver for various PC soundcards. 
The following cards are supported:

AdLib
SoundBlaster (1.0-2.0) and compatibles, including
  ThunderBoard and Ati Stereo F/X.
SoundBlaster Pro and SB Pro 2
SoundBlaster 16 (8 bit mono only)
ProAudioSpectrum 16
  (The original ProAudioSpectrum and the PAS+ are not supported 
  (and propably will remain unsupported)).

If you have any problems, please contact me.

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

- Since this driver is a part of the Linux kernel distribution, no
  special steps are required to build the driver itself.

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

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

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

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

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)

	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
hsavolai@cs.helsinki.fi

----------------- cut here ------------------------------
#!/bin/sh
#
#	soudinstall		
#
#		by Craig Metz - cmetz@thor.tjhsst.edu
#
# Create the devices
#
#	Mixer 		(14, 0)
#
if [ -e /dev/mixer ]; then 
	rm -f /dev/mixer 
fi
mknod -m 666 /dev/mixer c 14 0
#
#	Sequencer	(14, 1)
#
if [ -e /dev/sequencer ]; then
	rm -f /dev/sequencer
fi
mknod -m 666 /dev/sequencer c 14 1
#
#	MIDI		(14, 2)	[ Not implemented ]
#
if [ -e /dev/midi ]; then
	rm -f /dev/midi
fi
mknod -m 666 /dev/midi c 14 2
#
#	DSP		(14, 3)
#
if [ -e /dev/dsp ]; then
	rm -f /dev/dsp
fi
mknod -m 666 /dev/dsp c 14 3
#
#	SPARC audio	(14, 4)	[ Not fully implemented ]
#
if [ -e /dev/audio ]; then
	rm -f /dev/audio
fi
mknod -m 666 /dev/audio c 14 4
#
#	DSP2		(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) [ Not fully implemented ]
#				/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
