================================================================
	AWE32 Sound Driver for Linux / FreeBSD
		version 0.3.1; Jan. 11, 1997
================================================================

* GENERAL NOTES

This is a sound driver extension for SoundBlaster AWE32 and other
compatible cards (AWE32-PnP, SB32, SB32-PnP, AWE64 & etc) to enable
the wave synth operations.  The driver is provided for both Linux
1.2.x and 2.[01].x kernels, and also FreeBSD.  Consult the
installation document for installation on the original sound driver
package.

This driver was written by Takashi Iwai (iwai@dragon.mm.t.u-tokyo.ac.jp)  
who also maintains the code.  Please forward any questions, bug fixes
and suggestions directly to Iwai (_NOT_ to Linus Torvalds or Hannu
Savolainen).


* CAUTION

- On ver.0.3.1, some zero size array entries are removed from
awe_voice.h to avoid compile error in some non-ANSI compilers.
Due to this fix, the size of awe_voice_rec structure is changed from
older versions.  Use a constant AWE_VOICE_REC_SIZE instead of
sizeof(awe_voice_rec).
You can still have a compatibility by defining AWE_COMPAT_030=1, but
this feature will be omitted in the future release.


* NOTE TO LINUX USERS

To enable this driver on linux-2.[01].x kernels, you need turn on both 
"lowlevel drivers support" and "AWE32 synth support" options in sound
menu when configure your linux kernel and modules.  For more details,
see the installation document in the original driver package
(awedrv-0.x.x.tar.gz) available at the web page:
	http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/

If you're using PnP cards, the card must be initialized before loading
the sound driver.  There're several options to do this:
    - Initialize the card via ISA PnP tools, and load the sound module.
    - Initialize the card on DOS, and load linux by loadlin.exe
    - Use PnP driver (for Linux-2.0.x)
See the FAQ list on the URL above.


* COMPILE FLAGS

Compile conditions are defined in awe_config.h.

- AWE_OBSOLETE_VOXWARE		(default: not defined)
    indicates the system is VoxWare-3.0.x (with linux 1.2.x or
    FreeBSD) if defined.  This option will be set automatically when
    you use installation script.

- AWE_NEW_KERNEL_INTERFACE	(default: not defined)
    indicates the system is OSSLite on Linux 2.1.6 or later if
    defined.  This option will be set automatically when you use
    installation script.

- HAS_LOWLEVEL_H		(default: not defined)
    indicates the system has "lowlevel.h" in the sound/lowlevel
    directory.  OSS driver has this file.

- AWE_NO_PATCHMGR		(default: not defined)
    indicates the sound driver has no patch manager function (for
    OSS-3.707 (in Linux-2.1.13) or newer). 

- AWE_DEFAULT_BASE_ADDR		(default: not defined)
    specifies the base port address of your AWE32 card.
    Define this only when the driver couldn't detect your card
    properly. 

- AWE_DEFAULT_MEM_SIZE		(default: not defined)
    specifies the memory size of your AWE32 card by kilo bytes.
    Define this only when the driver couldn't detect memory size
    properly. 
    
- AWE_MAX_SAMPLES		(default: 400)
    specifies the maximum number of wave samples.
    The default size is set for the original GM and GS presets from
    CreativeLab.  If you have a large set of samples (eg 2MB & 8MB GM
    presets), increase this value to appropriate size. 

- AWE_MAX_INFOS			(default: 900)
    specifies the maximum number of instruments.
    The default size is set for the original GM and GS presets from
    CreativeLab.  If you have a large set of samples (eg 2MB & 8MB GM
    presets), increase this value to appropriate size. 

- AWE_ALWAYS_INIT_FM		(default: not defined)
    indicates the AWE driver always initialize FM passthrough even
    without DRAM on board.  Emu8000 chip has a restriction for playing
    samples on DRAM that at least two channels must be occupied as
    passthrough channels. 

- AWE_DEBUG_ON			(default: defined)
    turns on debuggin messages if defined.

- AWE_CHECKSUM_DATA		(default: defined)
    verifies check sum of sample data with the transferred data if
    defined. 

- AWE_CHECKSUM_MEMORY		(default: defined)
    Verifies check sum of sample data with the written data on DRAM.

- AWE_HAS_GUS_COMPATIBILITY	(default: defined)
    Enables GUS compatibility mode if defined, reading GUS patches and 
    GUS control commands.  Define this option to use GMOD or other
    GUS module players.

- AWE_ACCEPT_ALL_SOUNDS_CONTROL	(default: not defined)
    Enables MIDI control #120 and #123 as "all notes off" and "all
    sounds off" events, respectively.

- DEF_FM_CHORUS_DEPTH		(default: 0x10)
    The default strength to be sent to the chorus effect engine.
    From 0 to 0xff.  Larger numbers may often cause weird sounds.

- DEF_FM_REVERB_DEPTH		(default: 0x10)
    The default strength to be sent to the reverb effect engine.
    From 0 to 0xff.  Larger numbers may often cause weird sounds.


* USING THE DRIVER

To load SoundFont files, sfxload utility is required.
All AWE32 driver and utilities can be downloaded from:
	http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/

The GM and GS sounds include multiple instrument layers.  The older
driver couldn't handle multiple instruments.  The current version
supports this type of sounds with a special extension, but so far only 
drvmidi and playmidi can play the multiple instruments and stereo
sounds.

To play drvmidi, load the SoundFont file directly uing sfxload utility.

	% sfxload -i synthgm.sf2

To use other sequencers like musserver, some sounds may become
inaudible unless converting to SFX file.  Follow the instruction in
awesfx package to make patched GM and GS presets.  Then, load the SFX
file on driver by sfxload utility.

	% sfxload -i gm.sfx

Now you can hear midi musics by supported midi players
(awemidi-0.1.x.tar.gz or patch file to playmidi-2.3).

	% drvmidi foo.mid

Enjoy.


* ACKNOWLEDGMENTS

Thanks to Witold Jachimczyk (witek@xfactor.wpi.edu) for many advices
to programming of AWE32.  Many codes are brought from his AWE32-native 
MOD player, ALMP.
The port of awedrv0.1.6 to FreeBSD is done by Randall Hopper
(rhh@ct.picker.com).
I also thank linux-awe-ml members for their efforts
to reboot their system many times :-)


* BUGS & TODO'S

- More smart patch management
- More smart DRAM memory control
- Dynamic buffer allocation
- etc, etc, etc.


* COPYRIGHT

Copyright (C) 1996,1997 Takashi Iwai

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


Takashi Iwai <iwai@dragon.mm.t.u-tokyo.ac.jp>
