1================================================================
2	AWE32 Sound Driver for Linux / FreeBSD
3		version 0.4.3; Nov. 1, 1998
4
5	Takashi Iwai <iwai@ww.uni-erlangen.de>
6================================================================
7
8* GENERAL NOTES
9
10This is a sound driver extension for SoundBlaster AWE32 and other
11compatible cards (AWE32-PnP, SB32, SB32-PnP, AWE64 & etc) to enable
12the wave synth operations.  The driver is provided for Linux 1.2.x
13and 2.[012].x kernels, as well as FreeBSD, on Intel x86 and DEC
14Alpha systems.
15
16This driver was written by Takashi Iwai <iwai@ww.uni-erlangen.de>,
17and provided "as is".  The original source (awedrv-0.4.3.tar.gz) and
18binary packages are available on the following URL:
19	http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/
20Note that since the author is apart from this web site, the update is
21not frequent now.
22
23
24* NOTE TO LINUX USERS
25
26To enable this driver on linux-2.[01].x kernels, you need turn on
27"AWE32 synth" options in sound menu when configure your linux kernel
28and modules.  The precise installation procedure is described in the
29AWE64-Mini-HOWTO and linux-kernel/Documetation/sound/AWE32.
30
31If you're using PnP cards, the card must be initialized before loading
32the sound driver.  There're several options to do this:
33    - Initialize the card via ISA PnP tools, and load the sound module.
34    - Initialize the card on DOS, and load linux by loadlin.exe
35    - Use PnP kernel driver (for Linux-2.x.x)
36The detailed instruction for the solution using isapnp tools is found
37in many documents like above.  A brief instruction is also included in
38the installation document of this package.
39For PnP driver project, please refer to the following URL:
40	http://www-jcr.lmh.ox.ac.uk/~pnp/
41
42
43* USING THE DRIVER
44
45The awedrv has several different playing modes to realize easy channel
46allocation for MIDI songs.  To hear the exact sound quality, you need
47to obtain the extended sequencer program, drvmidi or playmidi-2.5.
48
49For playing MIDI files, you *MUST* load the soundfont file on the
50driver previously by sfxload utility.  Otherwise you'll here no sounds
51at all!  All the utilities and driver source packages are found in the
52above URL.  The sfxload program is included in the package
53awesfx-0.4.3.tgz.  Binary packages are available there, too.  See the
54instruction in each package for installation.
55
56Loading a soundfont file is very simple.  Just execute the command
57
58	% sfxload synthgm.sbk
59
60Then, sfxload transfers the file "synthgm.sbk" to the driver.
61Both SF1 and SF2 formats are accepted.
62
63Now you can hear midi musics by a midi player.
64
65	% drvmidi foo.mid
66
67If you run MIDI player after MOD player, you need to load soundfont
68files again, since MOD player programs clear the previous loaded
69samples by their own data.
70
71If you have only 512kb on the sound card, I recommend to use dynamic
72sample loading via -L option of drvmidi.  2MB GM/GS soundfont file is
73available in most midi files.
74
75	% sfxload synthgm
76	% drvmidi -L 2mbgmgs foo.mid
77
78This makes a big difference (believe me)!  For more details, please
79refer to the FAQ list which is available on the URL above.
80
81The current chorus, reverb and equalizer status can be changed by
82aweset utility program (included in awesfx package).  Note that
83some awedrv-native programs (like drvmidi and xmp) will change the
84current settings by themselves.  The aweset program is effective
85only for other programs like playmidi.
86
87Enjoy.
88
89
90* COMPILE FLAGS
91
92Compile conditions are defined in awe_config.h.
93
94[Compatibility Conditions]
95The following flags are defined automatically when using installation
96shell script.
97
98- AWE_MODULE_SUPPORT
99    indicates your Linux kernel supports module for each sound card
100    (in recent 2.1 or 2.2 kernels and unofficial patched 2.0 kernels
101    as distributed in the RH5.0 package).
102    This flag is automatically set when you're using 2.1.x kernels.
103    You can pass the base address and memory size via the following
104    module options,
105	io = base I/O port address (eg. 0x620)
106	memsize = DRAM size in kilobytes (eg. 512)
107    As default, AWE driver probes these values automatically.
108
109
110[Hardware Conditions]
111You DON'T have to define the following two values.
112Define them only when the driver couldn't detect the card properly.
113
114- AWE_DEFAULT_BASE_ADDR		(default: not defined)
115    specifies the base port address of your AWE32 card.
116    0 means to autodetect the address.
117
118- AWE_DEFAULT_MEM_SIZE		(default: not defined)
119    specifies the memory size of your AWE32 card in kilobytes.
120    -1 means to autodetect its size.
121
122
123[Sample Table Size]
124From ver.0.4.0, sample tables are allocated dynamically (except
125Linux-1.2.x system), so you need NOT to touch these parameters.
126Linux-1.2.x users may need to increase these values to appropriate size
127if the sound card is equipped with more DRAM.
128
129- AWE_MAX_SF_LISTS, AWE_MAX_SAMPLES, AWE_MAX_INFOS
130
131
132[Other Conditions]
133
134- AWE_ALWAYS_INIT_FM		(default: not defined)
135    indicates the AWE driver always initialize FM passthrough even
136    without DRAM on board.  Emu8000 chip has a restriction for playing
137    samples on DRAM that at least two channels must be occupied as
138    passthrough channels.
139
140- AWE_DEBUG_ON			(default: defined)
141    turns on debugging messages if defined.
142
143- AWE_HAS_GUS_COMPATIBILITY	(default: defined)
144    Enables GUS compatibility mode if defined, reading GUS patches and
145    GUS control commands.  Define this option to use GMOD or other
146    GUS module players.
147
148- CONFIG_AWE32_MIDIEMU		(default: defined)
149    Adds a MIDI emulation device by Emu8000 wavetable.  The emulation
150    device can be accessed as an external MIDI, and sends the MIDI
151    control codes directly.  XG and GS sysex/NRPN are accepted.
152    No MIDI input is supported.
153
154- CONFIG_AWE32_MIXER		(default: not defined)
155    Adds a mixer device for AWE32 bass/treble equalizer control.
156    You can access this device using /dev/mixer?? (usually mixer01).
157
158- AWE_USE_NEW_VOLUME_CALC	(default: defined)
159    Use the new method to calculate the volume change as compatible
160    with DOS/Win drivers.  This option can be toggled via aweset
161    program, or drvmidi player.
162
163- AWE_CHECK_VTARGET		(default: defined)
164    Check the current volume target value when searching for an
165    empty channel to allocate a new voice.  This is experimentally
166    implemented in this version.  (probably, this option doesn't
167    affect the sound quality severely...)
168
169- AWE_ALLOW_SAMPLE_SHARING	(default: defined)
170   Allow sample sharing for differently loaded patches.
171   This function is available only together with awesfx-0.4.3p3.
172   Note that this is still an experimental option.
173
174- DEF_FM_CHORUS_DEPTH		(default: 0x10)
175    The default strength to be sent to the chorus effect engine.
176    From 0 to 0xff.  Larger numbers may often cause weird sounds.
177
178- DEF_FM_REVERB_DEPTH		(default: 0x10)
179    The default strength to be sent to the reverb effect engine.
180    From 0 to 0xff.  Larger numbers may often cause weird sounds.
181
182
183* ACKNOWLEDGMENTS
184
185Thanks to Witold Jachimczyk (witek@xfactor.wpi.edu) for much advice
186on programming of AWE32.  Much code is brought from his AWE32-native
187MOD player, ALMP.
188The port of awedrv to FreeBSD is done by Randall Hopper
189(rhh@ct.picker.com).
190The new volume calculation routine was derived from Mark Weaver's
191ADIP compatible routines.
192I also thank linux-awe-ml members for their efforts
193to reboot their system many times :-)
194
195
196* TODO'S
197
198- Complete DOS/Win compatibility
199- DSP-like output
200
201
202* COPYRIGHT
203
204Copyright (C) 1996-1998 Takashi Iwai
205
206This program is free software; you can redistribute it and/or modify
207it under the terms of the GNU General Public License as published by
208the Free Software Foundation; either version 2 of the License, or
209(at your option) any later version.
210
211This program is distributed in the hope that it will be useful,
212but WITHOUT ANY WARRANTY; without even the implied warranty of
213MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
214GNU General Public License for more details.
215
216You should have received a copy of the GNU General Public License
217along with this program; if not, write to the Free Software
218Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
219