tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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
8Driver Status
9-------------
10
11Requires: Kernel 2.1.106 or later (the driver is included with kernels
122.1.109 and above)
13
14As of 7/22/1998, this driver is currently in *BETA* state. This means
15that it compiles and runs, and that I use it on my system (Linux
162.1.106) with some reasonably demanding applications and uses. I
17believe the code is approaching an initial "finished" state that
18provides bug-free support for the Tropez Plus.
19
20Please note that to date, the driver has ONLY been tested on a Tropez
21Plus. I would very much like to hear (and help out) people with Tropez
22and Maui cards, since I think the driver can support those cards as
23well.
24
25Finally, 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
27OSS/Free for Linux makes this rather unnecessary.
28
29Some Questions
30--------------
31
32**********************************************************************
330) 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**********************************************************************
541) What to do about MIDI interfaces ?
55**********************************************************************
56
57The Tropez Plus (and perhaps other WF cards) can in theory support up
58to 2 physical MIDI interfaces. One of these is connected to the
59ICS2115 chip (the WaveFront synth itself) and is controlled by
60MPU/UART-401 emulation code running as part of the WaveFront OS. The
61other is controlled by the CS4232 chip present on the board. However,
62physical access to the CS4232 connector is difficult, and it is
63unlikely (though not impossible) that you will want to use it.
64
65An older version of this driver introduced an additional kernel config
66variable which controlled whether or not the CS4232 MIDI interface was
67configured. Because of Alan Cox's work on modularizing the sound
68drivers, and now backporting them to 2.0.34 kernels, there seems to be
69little reason to support "static" configuration variables, and so this
70has been abandoned in favor of *only* module parameters. Specifying
71"mpuio" and "mpuirq" for the cs4232 parameter will result in the
72CS4232 MIDI interface being configured; leaving them unspecified will
73leave it unconfigured (and thus unusable).
74
75BTW, I have heard from one Tropez+ user that the CS4232 interface is
76more reliable than the ICS2115 one. I have had no problems with the
77latter, and I don't have the right cable to test the former one
78out. Reports welcome.
79
80**********************************************************************
812) Why does line XXX of the code look like this .... ?
82**********************************************************************
83
84Either because it's not finished yet, or because you're a better coder
85than I am, or because you don't understand some aspect of how the card
86or the code works.
87
88I absolutely welcome comments, criticisms and suggestions about the
89design and implementation of the driver.
90
91**********************************************************************
923) 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**********************************************************************
1114) How do I compile/install/use it ?
112**********************************************************************
113
114PART 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
119PART 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
127PART 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
153Here'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************************************************************
1896) How do I configure my card ?
190************************************************************
191
192You need to edit /etc/modprobe.conf. Here's mine (edited to show the
193relevant 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
205Things 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**********************************************************************
2187) What about firmware ?
219**********************************************************************
220
221Turtle Beach have not given me permission to distribute their firmware
222for the ICS2115. However, if you have a WaveFront card, then you
223almost certainly have the firmware, and if not, its freely available
224on their website, at:
225
226 http://www.tbeach.com/tbs/downloads/scardsdown.htm#tropezplus
227
228The file is called WFOS2001.MOT (for the Tropez+).
229
230This driver, however, doesn't use the pure firmware as distributed,
231but instead relies on a somewhat processed form of it. You can
232generate this very easily. Following an idea from Andrew Veliath's
233Pinnacle driver, the following flex program will generate the
234processed 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
245To 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
250and then use it like this:
251
252 ws < my-copy-of-the-oswf.mot-file > /etc/sound/wavefront.os
253
254If you put it somewhere else, you'll always have to use the wf_ospath
255module parameter (see below) or alter the source code.
256
257**********************************************************************
2587) How do I get it working ?
259**********************************************************************
260
261Optionally, you can reboot with the "new" kernel (even though the only
262changes have really been made to a module).
263
264Then, as root do:
265
266 modprobe wavefront
267
268You should get something like this in /var/log/messages:
269
270 WaveFront: firmware 1.20 already loaded.
271
272or
273
274 WaveFront: no response to firmware probe, assume raw.
275
276then:
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
285The whole process takes about 16 seconds, the longest waits being
286after reporting the hardware version (during the firmware download),
287and after reporting program status (during patch status inquiry). Its
288shorter (about 10 secs) if the firmware is already loaded (i.e. only
289warm reboots since the last firmware load).
290
291The "available DRAM" line will vary depending on how much added RAM
292your card has. Mine has 8MB.
293
294To 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
296to play a General MIDI file. Try the "-D 0" to hear the
297difference between sending MIDI to the WaveFront and using the OPL/3,
298which is the default (I think ...). If you have an external synth(s)
299hooked to the soundcard, you can use "-e" to route to the
300external synth(s) (in theory, -D 1 should work as well, but I think
301there is a bug in playmidi which prevents this from doing what it
302should).
303
304**********************************************************************
3058) What are the module parameters ?
306**********************************************************************
307
308Its best to read wavefront.c for this, but here is a summary:
309
310integers:
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.
329strings:
330 ospath - path to get to the pre-processed OS firmware.
331 (default: /etc/sound/wavefront.os)
332
333**********************************************************************
3349) Who should I contact if I have problems?
335**********************************************************************
336
337Just me: Paul Barton-Davis <pbd@op.net>
338
339