Linux-2.6.12-rc2
[linux-2.6.git] / Documentation / sound / oss / README.awe
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
10 This is a sound driver extension for SoundBlaster AWE32 and other
11 compatible cards (AWE32-PnP, SB32, SB32-PnP, AWE64 & etc) to enable
12 the wave synth operations.  The driver is provided for Linux 1.2.x
13 and 2.[012].x kernels, as well as FreeBSD, on Intel x86 and DEC
14 Alpha systems.
15
16 This driver was written by Takashi Iwai <iwai@ww.uni-erlangen.de>,
17 and provided "as is".  The original source (awedrv-0.4.3.tar.gz) and
18 binary packages are available on the following URL:
19         http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/
20 Note that since the author is apart from this web site, the update is
21 not frequent now.
22
23
24 * NOTE TO LINUX USERS
25
26 To 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
28 and modules.  The precise installation procedure is described in the
29 AWE64-Mini-HOWTO and linux-kernel/Documetation/sound/AWE32.
30
31 If you're using PnP cards, the card must be initialized before loading
32 the 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)
36 The detailed instruction for the solution using isapnp tools is found
37 in many documents like above.  A brief instruction is also included in
38 the installation document of this package.
39 For 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
45 The awedrv has several different playing modes to realize easy channel 
46 allocation for MIDI songs.  To hear the exact sound quality, you need
47 to obtain the extended sequencer program, drvmidi or playmidi-2.5.
48
49 For playing MIDI files, you *MUST* load the soundfont file on the
50 driver previously by sfxload utility.  Otherwise you'll here no sounds 
51 at all!  All the utilities and driver source packages are found in the
52 above URL.  The sfxload program is included in the package
53 awesfx-0.4.3.tgz.  Binary packages are available there, too.  See the
54 instruction in each package for installation.
55
56 Loading a soundfont file is very simple.  Just execute the command
57
58         % sfxload synthgm.sbk
59
60 Then, sfxload transfers the file "synthgm.sbk" to the driver.
61 Both SF1 and SF2 formats are accepted.
62
63 Now you can hear midi musics by a midi player.
64
65         % drvmidi foo.mid
66
67 If you run MIDI player after MOD player, you need to load soundfont
68 files again, since MOD player programs clear the previous loaded
69 samples by their own data.
70
71 If you have only 512kb on the sound card, I recommend to use dynamic
72 sample loading via -L option of drvmidi.  2MB GM/GS soundfont file is
73 available in most midi files.
74
75         % sfxload synthgm
76         % drvmidi -L 2mbgmgs foo.mid
77
78 This makes a big difference (believe me)!  For more details, please
79 refer to the FAQ list which is available on the URL above.
80
81 The current chorus, reverb and equalizer status can be changed by
82 aweset utility program (included in awesfx package).  Note that
83 some awedrv-native programs (like drvmidi and xmp) will change the
84 current settings by themselves.  The aweset program is effective
85 only for other programs like playmidi.
86
87 Enjoy.
88
89
90 * COMPILE FLAGS
91
92 Compile conditions are defined in awe_config.h.
93
94 [Compatibility Conditions]
95 The following flags are defined automatically when using installation
96 shell 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]
111 You DON'T have to define the following two values.
112 Define 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]
124 From ver.0.4.0, sample tables are allocated dynamically (except
125 Linux-1.2.x system), so you need NOT to touch these parameters.
126 Linux-1.2.x users may need to increase these values to appropriate size 
127 if 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
185 Thanks to Witold Jachimczyk (witek@xfactor.wpi.edu) for much advice
186 on programming of AWE32.  Much code is brought from his AWE32-native 
187 MOD player, ALMP.
188 The port of awedrv to FreeBSD is done by Randall Hopper
189 (rhh@ct.picker.com).
190 The new volume calculation routine was derived from Mark Weaver's
191 ADIP compatible routines.
192 I also thank linux-awe-ml members for their efforts
193 to 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
204 Copyright (C) 1996-1998 Takashi Iwai
205
206 This program is free software; you can redistribute it and/or modify
207 it under the terms of the GNU General Public License as published by
208 the Free Software Foundation; either version 2 of the License, or
209 (at your option) any later version.
210
211 This program is distributed in the hope that it will be useful,
212 but WITHOUT ANY WARRANTY; without even the implied warranty of
213 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
214 GNU General Public License for more details.
215
216 You should have received a copy of the GNU General Public License
217 along with this program; if not, write to the Free Software
218 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.