Documentation/sound/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 its 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/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 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
 154 Here'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 ************************************************************
 190 6) How do I configure my card ?
 191 ************************************************************
 192
 193 You need to edit /etc/modules.conf. Here's mine (edited to show the
 194 relevant 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
 207 Things 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 **********************************************************************
 220 7) What about firmware ?
 221 **********************************************************************
 222
 223 Turtle Beach have not given me permission to distribute their firmware
 224 for the ICS2115. However, if you have a WaveFront card, then you
 225 almost certainly have the firmware, and if not, its freely available
 226 on their website, at:
 227
 228    http://www.tbeach.com/tbs/downloads/scardsdown.htm#tropezplus
 229
 230 The file is called WFOS2001.MOT (for the Tropez+).
 231
 232 This driver, however, doesn't use the pure firmware as distributed,
 233 but instead relies on a somewhat processed form of it. You can
 234 generate this very easily. Following an idea from Andrew Veliath's
 235 Pinnacle driver, the following flex program will generate the
 236 processed 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
 247 To 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
 252 and then use it like this:
 253
 254     ws < my-copy-of-the-oswf.mot-file > /etc/sound/wavefront.os
 255
 256 If you put it somewhere else, you'll always have to use the wf_ospath
 257 module parameter (see below) or alter the source code.
 258
 259 **********************************************************************
 260 7) How do I get it working ?
 261 **********************************************************************
 262
 263 Optionally, you can reboot with the "new" kernel (even though the only
 264 changes have really been made to a module).
 265
 266 Then, as root do:
 267
 268      modprobe wavefront
 269
 270 You should get something like this in /var/log/messages:
 271
 272     WaveFront: firmware 1.20 already loaded.
 273
 274 or
 275
 276     WaveFront: no response to firmware probe, assume raw.
 277
 278 then:
 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
 287 The whole process takes about 16 seconds, the longest waits being
 288 after reporting the hardware version (during the firmware download),
 289 and after reporting program status (during patch status inquiry).  Its
 290 shorter (about 10 secs) if the firmware is already loaded (i.e. only
 291 warm reboots since the last firmware load).
 292
 293 The "available DRAM" line will vary depending on how much added RAM
 294 your card has. Mine has 8MB.
 295
 296 To 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
 298 to play a General MIDI file. Try the "-D 0" to hear the
 299 difference between sending MIDI to the WaveFront and using the OPL/3,
 300 which is the default (I think ...). If you have an external synth(s)
 301 hooked to the soundcard, you can use "-e" to route to the
 302 external synth(s) (in theory, -D 1 should work as well, but I think
 303 there is a bug in playmidi which prevents this from doing what it
 304 should).
 305
 306 **********************************************************************
 307 8) What are the module parameters ?
 308 **********************************************************************
 309
 310 Its best to read wavefront.c for this, but here is a summary:
 311
 312 integers:
 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.
 331 strings:
 332           ospath - path to get to the pre-processed OS firmware.
 333                     (default: /etc/sound/wavefront.os)
 334
 335 **********************************************************************
 336 9) Who should I contact if I have problems?
 337 **********************************************************************
 338
 339 Just me: Paul Barton-Davis <pbd@op.net>
 340
 341