Linux-2.6.12-rc2
[linux-2.6.git] / Documentation / sound / oss / Wavefront
1              An OSS/Free Driver for WaveFront soundcards
2                (Turtle Beach Maui, Tropez, Tropez Plus)
3
4                      Paul Barton-Davis, July 1998
5
6                           VERSION 0.2.5
7
8 Driver Status
9 -------------
10
11 Requires: Kernel 2.1.106 or later (the driver is included with kernels
12 2.1.109 and above)
13           
14 As of 7/22/1998, this driver is currently in *BETA* state. This means
15 that it compiles and runs, and that I use it on my system (Linux
16 2.1.106) with some reasonably demanding applications and uses.  I
17 believe the code is approaching an initial "finished" state that
18 provides bug-free support for the Tropez Plus.
19
20 Please note that to date, the driver has ONLY been tested on a Tropez
21 Plus. I would very much like to hear (and help out) people with Tropez
22 and Maui cards, since I think the driver can support those cards as
23 well. 
24
25 Finally, the driver has not been tested (or even compiled) as a static
26 (non-modular) part of the kernel. Alan Cox's good work in modularizing
27 OSS/Free for Linux makes this rather unnecessary.
28
29 Some Questions
30 --------------
31
32 **********************************************************************
33 0) What does this driver do that the maui driver did not ?
34 **********************************************************************
35
36 * can fully initialize a WaveFront card from cold boot - no DOS 
37           utilities needed
38 * working patch/sample/program loading and unloading (the maui
39       driver didn't document how to make this work, and assumed
40       user-level preparation of the patch data for writing
41       to the board. ick.)
42 * full user-level access to all WaveFront commands
43 * for the Tropez Plus, (primitive) control of the YSS225 FX processor
44 * Virtual MIDI mode supported - 2 MIDI devices accessible via the
45           WaveFront's MPU401/UART emulation. One
46           accesses the WaveFront synth, the other accesses the
47           external MIDI connector. Full MIDI read/write semantics
48           for both devices.
49 * OSS-compliant /dev/sequencer interface for the WaveFront synth,
50           including native and GUS-format patch downloading.
51 * semi-intelligent patch management (prototypical at this point)
52
53 **********************************************************************
54 1) What to do about MIDI interfaces ?
55 **********************************************************************
56
57 The Tropez Plus (and perhaps other WF cards) can in theory support up
58 to 2 physical MIDI interfaces. One of these is connected to the
59 ICS2115 chip (the WaveFront synth itself) and is controlled by
60 MPU/UART-401 emulation code running as part of the WaveFront OS.  The
61 other is controlled by the CS4232 chip present on the board. However,
62 physical access to the CS4232 connector is difficult, and it is
63 unlikely (though not impossible) that you will want to use it.
64
65 An older version of this driver introduced an additional kernel config
66 variable which controlled whether or not the CS4232 MIDI interface was
67 configured. Because of Alan Cox's work on modularizing the sound
68 drivers, and now backporting them to 2.0.34 kernels, there seems to be
69 little reason to support "static" configuration variables, and so this
70 has been abandoned in favor of *only* module parameters. Specifying
71 "mpuio" and "mpuirq" for the cs4232 parameter will result in the
72 CS4232 MIDI interface being configured; leaving them unspecified will
73 leave it unconfigured (and thus unusable).
74
75 BTW, I have heard from one Tropez+ user that the CS4232 interface is
76 more reliable than the ICS2115 one. I have had no problems with the
77 latter, and I don't have the right cable to test the former one
78 out. Reports welcome.
79
80 **********************************************************************
81 2) Why does line XXX of the code look like this .... ?
82 **********************************************************************
83
84 Either because it's not finished yet, or because you're a better coder
85 than I am, or because you don't understand some aspect of how the card
86 or the code works. 
87
88 I absolutely welcome comments, criticisms and suggestions about the
89 design and implementation of the driver. 
90
91 **********************************************************************
92 3) What files are included ?
93 **********************************************************************
94
95    drivers/sound/README.wavefront       -- this file
96
97    drivers/sound/wavefront.patch        -- patches for the 2.1.106 sound drivers
98                                            needed to make the rest of this work
99                                            DO NOT USE IF YOU'VE APPLIED THEM 
100                                            BEFORE, OR HAVE 2.1.109 OR ABOVE
101
102    drivers/sound/wavfront.c             -- the driver
103    drivers/sound/ys225.h                -- data declarations for FX config
104    drivers/sound/ys225.c                -- data definitions for FX config
105    drivers/sound/wf_midi.c              -- the "uart401" driver 
106                                               to support virtual MIDI mode.
107    include/wavefront.h                  -- the header file
108    Documentation/sound/oss/Tropez+          -- short docs on configuration
109
110 **********************************************************************
111 4) How do I compile/install/use it ?
112 **********************************************************************
113
114 PART ONE: install the source code into your sound driver directory
115
116   cd <top-of-your-2.1.106-code-base-e.g.-/usr/src/linux>
117   tar -zxvf <where-you-put/wavefront.tar.gz>
118
119 PART TWO: apply the patches
120
121      DO THIS ONLY IF YOU HAVE A KERNEL VERSION BELOW 2.1.109
122      AND HAVE NOT ALREADY INSTALLED THE PATCH(ES).
123
124   cd drivers/sound
125   patch < wavefront.patch
126
127 PART THREE: configure your kernel
128
129   cd <top of your kernel tree>
130   make xconfig (or whichever config option you use)
131
132          - choose YES for Sound Support       
133          - choose MODULE (M) for OSS Sound Modules
134          - choose MODULE(M) to YM3812/OPL3 support
135          - choose MODULE(M) for WaveFront support
136          - choose MODULE(M) for CS4232 support
137
138          - choose "N" for everything else (unless you have other
139               soundcards you want support for)
140
141
142    make boot
143    .
144    .
145    .
146    <whatever you normally do for a kernel install>
147    make modules
148    .
149    .
150    .
151    make modules_install
152
153 Here's my autoconf.h SOUND section:
154
155 /*
156  * Sound
157  */
158 #define CONFIG_SOUND 1
159 #undef  CONFIG_SOUND_OSS
160 #define CONFIG_SOUND_OSS_MODULE 1
161 #undef  CONFIG_SOUND_PAS
162 #undef  CONFIG_SOUND_SB
163 #undef  CONFIG_SOUND_ADLIB
164 #undef  CONFIG_SOUND_GUS
165 #undef  CONFIG_SOUND_MPU401
166 #undef  CONFIG_SOUND_PSS
167 #undef  CONFIG_SOUND_MSS
168 #undef  CONFIG_SOUND_SSCAPE
169 #undef  CONFIG_SOUND_TRIX
170 #undef  CONFIG_SOUND_MAD16
171 #undef  CONFIG_SOUND_WAVEFRONT
172 #define CONFIG_SOUND_WAVEFRONT_MODULE 1
173 #undef  CONFIG_SOUND_CS4232
174 #define CONFIG_SOUND_CS4232_MODULE 1
175 #undef  CONFIG_SOUND_MAUI
176 #undef  CONFIG_SOUND_SGALAXY
177 #undef  CONFIG_SOUND_OPL3SA1
178 #undef  CONFIG_SOUND_SOFTOSS
179 #undef  CONFIG_SOUND_YM3812
180 #define CONFIG_SOUND_YM3812_MODULE 1
181 #undef  CONFIG_SOUND_VMIDI
182 #undef  CONFIG_SOUND_UART6850
183 /*
184  * Additional low level sound drivers
185  */
186 #undef  CONFIG_LOWLEVEL_SOUND
187
188 ************************************************************
189 6) How do I configure my card ?
190 ************************************************************
191
192 You need to edit /etc/modprobe.conf. Here's mine (edited to show the
193 relevant details):
194
195   # Sound system
196   alias char-major-14-* wavefront
197   alias synth0 wavefront
198   alias mixer0 cs4232
199   alias audio0 cs4232
200   install wavefront /sbin/modprobe cs4232 && /sbin/modprobe -i wavefront && /sbin/modprobe opl3
201   options wavefront io=0x200 irq=9
202   options cs4232 synthirq=9 synthio=0x200 io=0x530 irq=5 dma=1 dma2=0
203   options opl3 io=0x388
204
205 Things to note: 
206
207        the wavefront options "io" and "irq" ***MUST*** match the "synthio"
208        and "synthirq" cs4232 options.
209
210        you can do without the opl3 module if you don't
211        want to use the OPL/[34] FM synth on the soundcard
212
213        the opl3 io parameter is conventionally not adjustable.
214        In theory, any not-in-use IO port address would work, but
215        just use 0x388 and stick with the crowd.
216
217 **********************************************************************
218 7) What about firmware ?
219 **********************************************************************
220
221 Turtle Beach have not given me permission to distribute their firmware
222 for the ICS2115. However, if you have a WaveFront card, then you
223 almost certainly have the firmware, and if not, its freely available
224 on their website, at:
225
226    http://www.tbeach.com/tbs/downloads/scardsdown.htm#tropezplus 
227
228 The file is called WFOS2001.MOT (for the Tropez+).
229
230 This driver, however, doesn't use the pure firmware as distributed,
231 but instead relies on a somewhat processed form of it. You can
232 generate this very easily. Following an idea from Andrew Veliath's
233 Pinnacle driver, the following flex program will generate the
234 processed version:
235
236 ---- cut here -------------------------
237 %option main
238 %%
239 ^S[28].*\r$ printf ("%c%.*s", yyleng-1,yyleng-1,yytext);
240 <<EOF>> { fputc ('\0', stdout); return; }
241 \n {} 
242 .  {}
243 ---- cut here -------------------------
244
245 To use it, put the above in file (say, ws.l) compile it like this:
246
247       shell> flex -ows.c ws.l
248       shell> cc -o ws ws.c
249       
250 and then use it like this:
251
252     ws < my-copy-of-the-oswf.mot-file > /etc/sound/wavefront.os
253
254 If you put it somewhere else, you'll always have to use the wf_ospath
255 module parameter (see below) or alter the source code.
256
257 **********************************************************************
258 7) How do I get it working ?
259 **********************************************************************
260
261 Optionally, you can reboot with the "new" kernel (even though the only
262 changes have really been made to a module).
263
264 Then, as root do:
265
266      modprobe wavefront
267
268 You should get something like this in /var/log/messages:
269
270     WaveFront: firmware 1.20 already loaded.
271
272 or 
273
274     WaveFront: no response to firmware probe, assume raw.
275
276 then:
277
278     WaveFront: waiting for memory configuration ...
279     WaveFront: hardware version 1.64
280     WaveFront: available DRAM 8191k
281     WaveFront: 332 samples used (266 real, 13 aliases, 53 multi), 180 empty
282     WaveFront: 128 programs slots in use
283     WaveFront: 256 patch slots filled, 142 in use
284
285 The whole process takes about 16 seconds, the longest waits being
286 after reporting the hardware version (during the firmware download),
287 and after reporting program status (during patch status inquiry).  Its
288 shorter (about 10 secs) if the firmware is already loaded (i.e. only
289 warm reboots since the last firmware load).
290
291 The "available DRAM" line will vary depending on how much added RAM
292 your card has. Mine has 8MB.
293
294 To check basically functionality, use play(1) or splay(1) to send a
295 .WAV or other audio file through the audio portion. Then use playmidi
296 to play a General MIDI file. Try the "-D 0" to hear the
297 difference between sending MIDI to the WaveFront and using the OPL/3,
298 which is the default (I think ...). If you have an external synth(s)
299 hooked to the soundcard, you can use "-e" to route to the
300 external synth(s) (in theory, -D 1 should work as well, but I think
301 there is a bug in playmidi which prevents this from doing what it
302 should). 
303
304 **********************************************************************
305 8) What are the module parameters ?
306 **********************************************************************
307
308 Its best to read wavefront.c for this, but here is a summary:
309
310 integers: 
311           wf_raw  - if set, ignore apparent presence of firmware
312                     loaded onto the ICS2115, reset the whole
313                     board, and initialize it from scratch. (default = 0)
314
315           fx_raw  - if set, always initialize the YSS225 processor
316                     on the Tropez plus. (default = 1)
317
318           < The next 4 are basically for kernel hackers to allow
319             tweaking the driver for testing purposes. >             
320
321           wait_usecs        -  loop timer used when waiting for
322                                status conditions on the board. 
323                                The default is 150.
324
325           debug_default    - debugging flags. See sound/wavefront.h
326                              for WF_DEBUG_* values. Default is zero.
327                              Setting this allows you to debug the
328                              driver during module installation.
329 strings:
330           ospath - path to get to the pre-processed OS firmware.
331                     (default: /etc/sound/wavefront.os)
332
333 **********************************************************************
334 9) Who should I contact if I have problems?
335 **********************************************************************
336
337 Just me: Paul Barton-Davis <pbd@op.net>
338
339