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