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 its 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/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 dep 143 make boot 144 . 145 . 146 . 147 <whatever you normally do for a kernel install> 148 make modules 149 . 150 . 151 . 152 make modules_install 153 154Here's my autoconf.h SOUND section: 155 156/* 157 * Sound 158 */ 159#define CONFIG_SOUND 1 160#undef CONFIG_SOUND_OSS 161#define CONFIG_SOUND_OSS_MODULE 1 162#undef CONFIG_SOUND_PAS 163#undef CONFIG_SOUND_SB 164#undef CONFIG_SOUND_ADLIB 165#undef CONFIG_SOUND_GUS 166#undef CONFIG_SOUND_MPU401 167#undef CONFIG_SOUND_PSS 168#undef CONFIG_SOUND_MSS 169#undef CONFIG_SOUND_SSCAPE 170#undef CONFIG_SOUND_TRIX 171#undef CONFIG_SOUND_MAD16 172#undef CONFIG_SOUND_WAVEFRONT 173#define CONFIG_SOUND_WAVEFRONT_MODULE 1 174#undef CONFIG_SOUND_CS4232 175#define CONFIG_SOUND_CS4232_MODULE 1 176#undef CONFIG_SOUND_MAUI 177#undef CONFIG_SOUND_SGALAXY 178#undef CONFIG_SOUND_OPL3SA1 179#undef CONFIG_SOUND_SOFTOSS 180#undef CONFIG_SOUND_YM3812 181#define CONFIG_SOUND_YM3812_MODULE 1 182#undef CONFIG_SOUND_VMIDI 183#undef CONFIG_SOUND_UART6850 184/* 185 * Additional low level sound drivers 186 */ 187#undef CONFIG_LOWLEVEL_SOUND 188 189************************************************************ 1906) How do I configure my card ? 191************************************************************ 192 193You need to edit /etc/modules.conf. Here's mine (edited to show the 194relevant details): 195 196 # Sound system 197 alias char-major-14 wavefront 198 alias synth0 wavefront 199 alias mixer0 cs4232 200 alias audio0 cs4232 201 pre-install wavefront modprobe "-k" "cs4232" 202 post-install wavefront modprobe "-k" "opl3" 203 options wavefront io=0x200 irq=9 204 options cs4232 synthirq=9 synthio=0x200 io=0x530 irq=5 dma=1 dma2=0 205 options opl3 io=0x388 206 207Things to note: 208 209 the wavefront options "io" and "irq" ***MUST*** match the "synthio" 210 and "synthirq" cs4232 options. 211 212 you can do without the opl3 module if you don't 213 want to use the OPL/[34] FM synth on the soundcard 214 215 the opl3 io parameter is conventionally not adjustable. 216 In theory, any not-in-use IO port address would work, but 217 just use 0x388 and stick with the crowd. 218 219********************************************************************** 2207) What about firmware ? 221********************************************************************** 222 223Turtle Beach have not given me permission to distribute their firmware 224for the ICS2115. However, if you have a WaveFront card, then you 225almost certainly have the firmware, and if not, its freely available 226on their website, at: 227 228 http://www.tbeach.com/tbs/downloads/scardsdown.htm#tropezplus 229 230The file is called WFOS2001.MOT (for the Tropez+). 231 232This driver, however, doesn't use the pure firmware as distributed, 233but instead relies on a somewhat processed form of it. You can 234generate this very easily. Following an idea from Andrew Veliath's 235Pinnacle driver, the following flex program will generate the 236processed version: 237 238---- cut here ------------------------- 239%option main 240%% 241^S[28].*\r$ printf ("%c%.*s", yyleng-1,yyleng-1,yytext); 242<<EOF>> { fputc ('\0', stdout); return; } 243\n {} 244. {} 245---- cut here ------------------------- 246 247To use it, put the above in file (say, ws.l) compile it like this: 248 249 shell> flex -ows.c ws.l 250 shell> cc -o ws ws.c 251 252and then use it like this: 253 254 ws < my-copy-of-the-oswf.mot-file > /etc/sound/wavefront.os 255 256If you put it somewhere else, you'll always have to use the wf_ospath 257module parameter (see below) or alter the source code. 258 259********************************************************************** 2607) How do I get it working ? 261********************************************************************** 262 263Optionally, you can reboot with the "new" kernel (even though the only 264changes have really been made to a module). 265 266Then, as root do: 267 268 modprobe wavefront 269 270You should get something like this in /var/log/messages: 271 272 WaveFront: firmware 1.20 already loaded. 273 274or 275 276 WaveFront: no response to firmware probe, assume raw. 277 278then: 279 280 WaveFront: waiting for memory configuration ... 281 WaveFront: hardware version 1.64 282 WaveFront: available DRAM 8191k 283 WaveFront: 332 samples used (266 real, 13 aliases, 53 multi), 180 empty 284 WaveFront: 128 programs slots in use 285 WaveFront: 256 patch slots filled, 142 in use 286 287The whole process takes about 16 seconds, the longest waits being 288after reporting the hardware version (during the firmware download), 289and after reporting program status (during patch status inquiry). Its 290shorter (about 10 secs) if the firmware is already loaded (i.e. only 291warm reboots since the last firmware load). 292 293The "available DRAM" line will vary depending on how much added RAM 294your card has. Mine has 8MB. 295 296To check basically functionality, use play(1) or splay(1) to send a 297.WAV or other audio file through the audio portion. Then use playmidi 298to play a General MIDI file. Try the "-D 0" to hear the 299difference between sending MIDI to the WaveFront and using the OPL/3, 300which is the default (I think ...). If you have an external synth(s) 301hooked to the soundcard, you can use "-e" to route to the 302external synth(s) (in theory, -D 1 should work as well, but I think 303there is a bug in playmidi which prevents this from doing what it 304should). 305 306********************************************************************** 3078) What are the module parameters ? 308********************************************************************** 309 310Its best to read wavefront.c for this, but here is a summary: 311 312integers: 313 wf_raw - if set, ignore apparent presence of firmware 314 loaded onto the ICS2115, reset the whole 315 board, and initialize it from scratch. (default = 0) 316 317 fx_raw - if set, always initialize the YSS225 processor 318 on the Tropez plus. (default = 1) 319 320 < The next 4 are basically for kernel hackers to allow 321 tweaking the driver for testing purposes. > 322 323 wait_usecs - loop timer used when waiting for 324 status conditions on the board. 325 The default is 150. 326 327 debug_default - debugging flags. See sound/wavefront.h 328 for WF_DEBUG_* values. Default is zero. 329 Setting this allows you to debug the 330 driver during module installation. 331strings: 332 ospath - path to get to the pre-processed OS firmware. 333 (default: /etc/sound/wavefront.os) 334 335********************************************************************** 3369) Who should I contact if I have problems? 337********************************************************************** 338 339Just me: Paul Barton-Davis <pbd@op.net> 340 341 342