linux/Documentation/sound/oss/README.OSS
<<
>>
Prefs
   1Introduction
   2------------
   3
   4This file is a collection of all the old Readme files distributed with
   5OSS/Lite by Hannu Savolainen. Since the new Linux sound driver is founded
   6on it I think these information may still be interesting for users that
   7have to configure their sound system.
   8
   9Be warned: Alan Cox is the current maintainer of the Linux sound driver so if
  10you have problems with it, please contact him or the current device-specific
  11driver maintainer (e.g. for aedsp16 specific problems contact me). If you have
  12patches, contributions or suggestions send them to Alan: I'm sure they are
  13welcome.
  14
  15In this document you will find a lot of references about OSS/Lite or ossfree:
  16they are gone forever. Keeping this in mind and with a grain of salt this
  17document can be still interesting and very helpful.
  18
  19[ File edited 17.01.1999 - Riccardo Facchetti ]
  20[ Edited miroSOUND section 19.04.2001 - Robert Siemer ]
  21
  22OSS/Free version 3.8 release notes
  23----------------------------------
  24
  25Please read the SOUND-HOWTO (available from sunsite.unc.edu and other Linux FTP 
  26sites). It gives instructions about using sound with Linux. It's bit out of
  27date but still very useful. Information about bug fixes and such things
  28is available from the web page (see above).
  29
  30Please check http://www.opensound.com/pguide for more info about programming
  31with OSS API.
  32
  33   ====================================================
  34-  THIS VERSION ____REQUIRES____ Linux 2.1.57 OR LATER.
  35   ====================================================
  36
  37Packages "snd-util-3.8.tar.gz" and "snd-data-0.1.tar.Z"
  38contain useful utilities to be used with this driver.
  39See http://www.opensound.com/ossfree/ for
  40download instructions.
  41
  42If you are looking for the installation instructions, please
  43look forward into this document.
  44
  45Supported sound cards
  46---------------------
  47
  48See below.
  49
  50Contributors
  51------------
  52
  53This driver contains code by several contributors. In addition several other
  54persons have given useful suggestions. The following is a list of major
  55contributors. (I could have forgotten some names.)
  56
  57        Craig Metz      1/2 of the PAS16 Mixer and PCM support
  58        Rob Hooft       Volume computation algorithm for the FM synth.
  59        Mika Liljeberg  uLaw encoding and decoding routines
  60        Jeff Tranter    Linux SOUND HOWTO document
  61        Greg Lee        Volume computation algorithm for the GUS and
  62                        lots of valuable suggestions.
  63        Andy Warner     ISC port
  64        Jim Lowe,
  65        Amancio Hasty Jr        FreeBSD/NetBSD port
  66        Anders Baekgaard        Bug hunting and valuable suggestions.
  67        Joerg Schubert  SB16 DSP support (initial version).
  68        Andrew Robinson Improvements to the GUS driver
  69        Megens SA       MIDI recording for SB and SB Pro (initial version).
  70        Mikael Nordqvist  Linear volume support for GUS and
  71                          nonblocking /dev/sequencer.
  72        Ian Hartas              SVR4.2 port
  73        Markus Aroharju and
  74        Risto Kankkunen         Major contributions to the mixer support
  75                                of GUS v3.7.
  76        Hunyue Yau      Mixer support for SG NX Pro.
  77        Marc Hoffman    PSS support (initial version).
  78        Rainer Vranken  Initialization for Jazz16 (initial version).
  79        Peter Trattler  Initial version of loadable module support for Linux.
  80        JRA Gibson      16 bit mode for Jazz16 (initial version)
  81        Davor Jadrijevic MAD16 support (initial version)
  82        Gregor Hoffleit Mozart support (initial version)
  83        Riccardo Facchetti Audio Excel DSP 16 (aedsp16) support
  84        James Hightower Spotting a tiny but important bug in CS423x support.
  85        Denis Sablic    OPTi 82C924 specific enhancements (non PnP mode)
  86        Tim MacKenzie   Full duplex support for OPTi 82C930.
  87        
  88        Please look at lowlevel/README for more contributors.
  89
  90There are probably many other names missing. If you have sent me some
  91patches and your name is not in the above list, please inform me.
  92
  93Sending your contributions or patches
  94-------------------------------------
  95
  96First of all it's highly recommended to contact me before sending anything
  97or before even starting to do any work. Tell me what you suggest to be
  98changed or what you have planned to do. Also ensure you are using the
  99very latest (development) version of OSS/Free since the change may already be
 100implemented there. In general it's a major waste of time to try to improve a
 101several months old version. Information about the latest version can be found
 102from http://www.opensound.com/ossfree. In general there is no point in
 103sending me patches relative to production kernels.
 104
 105Sponsors etc.
 106-------------
 107
 108The following companies have greatly helped development of this driver 
 109in form of a free copy of their product:
 110
 111Novell, Inc.            UnixWare personal edition + SDK
 112The Santa Cruz Operation, Inc.  A SCO OpenServer + SDK
 113Ensoniq Corp,           a SoundScape card and extensive amount of assistance
 114MediaTrix Peripherals Inc, a AudioTrix Pro card + SDK
 115Acer, Inc.              a pair of AcerMagic S23 cards.
 116
 117In addition the following companies have provided me sufficient amount
 118of technical information at least some of their products (free or $$$):
 119
 120Advanced Gravis Computer Technology Ltd.
 121Media Vision Inc.
 122Analog Devices Inc.
 123Logitech Inc.
 124Aztech Labs Inc.
 125Crystal Semiconductor Corporation,
 126Integrated Circuit Systems Inc.
 127OAK Technology
 128OPTi
 129Turtle Beach
 130miro
 131Ad Lib Inc. ($$)
 132Music Quest Inc. ($$)
 133Creative Labs ($$$)
 134
 135If you have some problems
 136=========================
 137
 138Read the sound HOWTO (sunsite.unc.edu:/pub/Linux/docs/...?).
 139Also look at the home page (http://www.opensound.com/ossfree). It may
 140contain info about some recent bug fixes.
 141
 142It's likely that you have some problems when trying to use the sound driver
 143first time. Sound cards don't have standard configuration so there are no
 144good default configuration to use. Please try to use same I/O, DMA and IRQ
 145values for the sound card than with DOS.
 146
 147If you get an error message when trying to use the driver, please look
 148at /var/adm/messages for more verbose error message.
 149
 150
 151The following errors are likely with /dev/dsp and /dev/audio.
 152
 153        - "No such device or address".
 154        This error indicates that there are no suitable hardware for the
 155        device file or the sound driver has been compiled without support for
 156        this particular device. For example /dev/audio and /dev/dsp will not
 157        work if "digitized voice support" was not enabled during "make config".
 158        
 159        - "Device or resource busy". Probably the IRQ (or DMA) channel 
 160        required by the sound card is in use by some other device/driver.
 161
 162        - "I/O error". Almost certainly (99%) it's an IRQ or DMA conflict.
 163        Look at the kernel messages in /var/adm/notice for more info.
 164
 165        - "Invalid argument". The application is calling ioctl()
 166        with impossible parameters. Check that the application is
 167        for sound driver version 2.X or later.
 168
 169Linux installation
 170==================
 171
 172IMPORTANT!      Read this if you are installing a separately
 173                distributed version of this driver.
 174
 175                Check that your kernel version works with this
 176                release of the driver (see Readme). Also verify
 177                that your current kernel version doesn't have more
 178                recent sound driver version than this one. IT'S HIGHLY
 179                RECOMMENDED THAT YOU USE THE SOUND DRIVER VERSION THAT
 180                IS DISTRIBUTED WITH KERNEL SOURCES.
 181
 182- When installing separately distributed sound driver you should first
 183  read the above notice. Then try to find proper directory where and how
 184  to install the driver sources. You should not try to install a separately
 185  distributed driver version if you are not able to find the proper way
 186  yourself (in this case use the version that is distributed with kernel
 187  sources). Remove old version of linux/drivers/sound directory before
 188  installing new files.
 189
 190- To build the device files you need to run the enclosed shell script 
 191  (see below). You need to do this only when installing sound driver
 192  first time or when upgrading to much recent version than the earlier
 193  one.
 194
 195- Configure and compile Linux as normally (remember to include the
 196  sound support during "make config"). Please refer to kernel documentation
 197  for instructions about configuring and compiling kernel. File Readme.cards
 198  contains card specific instructions for configuring this driver for
 199  use with various sound cards.
 200
 201Boot time configuration (using lilo and insmod) 
 202-----------------------------------------------
 203
 204This information has been removed. Too many users didn't believe
 205that it's really not necessary to use this method. Please look at
 206Readme of sound driver version 3.0.1 if you still want to use this method.
 207
 208Problems
 209--------
 210
 211Common error messages:
 212
 213- /dev/???????: No such file or directory.
 214Run the script at the end of this file.
 215
 216- /dev/???????: No such device.
 217You are not running kernel which contains the sound driver. When using
 218modularized sound driver this error means that the sound driver is not
 219loaded.
 220
 221- /dev/????: No such device or address.
 222Sound driver didn't detect suitable card when initializing. Please look at
 223Readme.cards for info about configuring the driver with your card. Also
 224check for possible boot (insmod) time error messages in /var/adm/messages.
 225
 226- Other messages or problems
 227Please check http://www.opensound.com/ossfree for more info.
 228
 229Configuring version 3.8 (for Linux) with some common sound cards
 230================================================================
 231
 232This document describes configuring sound cards with the freeware version of
 233Open Sound Systems (OSS/Free). Information about the commercial version
 234(OSS/Linux) and its configuration is available from 
 235http://www.opensound.com/linux.html. Information presented here is
 236not valid for OSS/Linux. 
 237
 238If you are unsure about how to configure OSS/Free
 239you can download the free evaluation version of OSS/Linux from the above
 240address. There is a chance that it can autodetect your sound card. In this case
 241you can use the information included in soundon.log when configuring OSS/Free.
 242
 243
 244IMPORTANT!      This document covers only cards that were "known" when
 245                this driver version was released. Please look at
 246                http://www.opensound.com/ossfree for info about
 247                cards introduced recently.
 248
 249                When configuring the sound driver, you should carefully
 250                check each sound configuration option (particularly
 251                "Support for /dev/dsp and /dev/audio"). The default values
 252                offered by these programs are not necessarily valid.
 253
 254
 255THE BIGGEST MISTAKES YOU CAN MAKE
 256=================================
 257
 2581. Assuming that the card is Sound Blaster compatible when it's not.
 259--------------------------------------------------------------------
 260
 261The number one mistake is to assume that your card is compatible with
 262Sound Blaster. Only the cards made by Creative Technology or which have
 263one or more chips labeled by Creative are SB compatible. In addition there
 264are few sound chipsets which are SB compatible in Linux such as ESS1688 or
 265Jazz16. Note that SB compatibility in DOS/Windows does _NOT_ mean anything
 266in Linux. 
 267
 268IF YOU REALLY ARE 150% SURE YOU HAVE A SOUND BLASTER YOU CAN SKIP THE REST OF
 269THIS CHAPTER.
 270
 271For most other "supposed to be SB compatible" cards you have to use other
 272than SB drivers (see below).  It is possible to get most sound cards to work
 273in SB mode but in general it's a complete waste of time. There are several
 274problems which you will encounter by using SB mode with cards that are not
 275truly SB compatible:
 276
 277- The SB emulation is at most SB Pro (DSP version 3.x) which means that 
 278you get only 8 bit audio (there is always an another ("native") mode which
 279gives the 16 bit capability). The 8 bit only operation is the reason why
 280many users claim that sound quality in Linux is much worse than in DOS.
 281In addition some applications require 16 bit mode and they produce just
 282noise with a 8 bit only device.
 283- The card may work only in some cases but refuse to work most of the
 284time. The SB compatible mode always requires special initialization which is 
 285done by the DOS/Windows drivers. This kind of cards work in Linux after
 286you have warm booted it after DOS but they don't work after cold boot
 287(power on or reset).
 288- You get the famous "DMA timed out" messages. Usually all SB clones have
 289software selectable IRQ and DMA settings. If the (power on default) values
 290currently used by the card don't match configuration of the driver you will
 291get the above error message whenever you try to record or play. There are
 292few other reasons to the DMA timeout message but using the SB mode seems
 293to be the most common cause.
 294
 2952. Trying to use a PnP (Plug & Play) card just like an ordinary sound card
 296--------------------------------------------------------------------------
 297
 298Plug & Play is a protocol defined by Intel and Microsoft. It lets operating
 299systems to easily identify and reconfigure I/O ports, IRQs and DMAs of ISA
 300cards. The problem with PnP cards is that the standard Linux doesn't currently
 301(versions 2.1.x and earlier) don't support PnP. This means that you will have
 302to use some special tricks (see later) to get a PnP card alive. Many PnP cards
 303work after they have been initialized but this is not always the case.
 304
 305There are sometimes both PnP and non-PnP versions of the same sound card.
 306The non-PnP version is the original model which usually has been discontinued
 307more than an year ago. The PnP version has the same name but with "PnP"
 308appended to it (sometimes not). This causes major confusion since the non-PnP
 309model works with Linux but the PnP one doesn't.
 310
 311You should carefully check if "Plug & Play" or "PnP" is mentioned in the name
 312of the card or in the documentation or package that came with the card. 
 313Everything described in the rest of this document is not necessarily valid for
 314PnP models of sound cards even you have managed to wake up the card properly.
 315Many PnP cards are simply too different from their non-PnP ancestors which are
 316covered by this document.
 317
 318
 319Cards that are not (fully) supported by this driver
 320===================================================
 321
 322See http://www.opensound.com/ossfree for information about sound cards 
 323to be supported in future. 
 324
 325
 326How to use sound without recompiling kernel and/or sound driver
 327===============================================================
 328
 329There is a commercial sound driver which comes in precompiled form and doesn't
 330require recompiling of the kernel. See http://www.4Front-tech.com/oss.html for
 331more info.
 332
 333
 334Configuring PnP cards
 335=====================
 336
 337New versions of most sound cards use the so-called ISA PnP protocol for
 338soft configuring their I/O, IRQ, DMA and shared memory resources.
 339Currently at least cards made by Creative Technology (SB32 and SB32AWE
 340PnP), Gravis (GUS PnP and GUS PnP Pro), Ensoniq (Soundscape PnP) and
 341Aztech (some Sound Galaxy models) use PnP technology. The CS4232/4236 audio
 342chip by Crystal Semiconductor (Intel Atlantis, HP Pavilion and many other
 343motherboards) is also based on PnP technology but there is a "native" driver
 344available for it (see information about CS4232 later in this document).
 345
 346PnP sound cards (as well as most other PnP ISA cards) are not supported
 347by this version of the driver . Proper
 348support for them should be released during 97 once the kernel level
 349PnP support is available.
 350
 351There is a method to get most of the PnP cards to work. The basic method
 352is the following:
 353
 3541) Boot DOS so the card's DOS drivers have a chance to initialize it.
 3552) _Cold_ boot to Linux by using "loadlin.exe".  Hitting ctrl-alt-del
 356works with older machines but causes a hard reset of all cards on recent
 357(Pentium) machines.
 3583) If you have the sound driver in Linux configured properly, the card should
 359work now. "Proper" means that I/O, IRQ and DMA settings are the same as in
 360DOS. The hard part is to find which settings were used. See the documentation of
 361your card for more info.
 362
 363Windows 95 could work as well as DOS but running loadlin may be difficult.
 364Probably you should "shut down" your machine to MS-DOS mode before running it.
 365
 366Some machines have a BIOS utility for setting PnP resources. This is a good
 367way to configure some cards. In this case you don't need to boot DOS/Win95
 368before starting Linux.
 369
 370Another way to initialize PnP cards without DOS/Win95 is a Linux based
 371PnP isolation tool. When writing this there is a pre alpha test version
 372of such a tool available from ftp://ftp.demon.co.uk/pub/unix/linux/utils. The
 373file is called isapnptools-*. Please note that this tool is just a temporary
 374solution which may be incompatible with future kernel versions having proper
 375support for PnP cards. There are bugs in setting DMA channels in earlier
 376versions of isapnptools so at least version 1.6 is required with sound cards.
 377
 378Yet another way to use PnP cards is to use (commercial) OSS/Linux drivers.  See
 379http://www.opensound.com/linux.html for more info. This is probably the way you
 380should do it if you don't want to spend time recompiling the kernel and 
 381required tools.
 382
 383
 384Read this before trying to configure the driver
 385===============================================
 386
 387There are currently many cards that work with this driver. Some of the cards
 388have native support while others work since they emulate some other
 389card (usually SB, MSS/WSS and/or MPU401). The following cards have native
 390support in the driver. Detailed instructions for configuring these cards
 391will be given later in this document.
 392
 393Pro Audio Spectrum 16 (PAS16) and compatibles:
 394        Pro Audio Spectrum 16
 395        Pro Audio Studio 16
 396        Logitech Sound Man 16
 397        NOTE! The original Pro Audio Spectrum as well as the PAS+ are not
 398              and will not be supported by the driver.
 399
 400Media Vision Jazz16 based cards
 401        Pro Sonic 16
 402        Logitech SoundMan Wave
 403        (Other Jazz based cards should work but I don't have any reports
 404        about them).
 405
 406Sound Blasters
 407        SB 1.0 to 2.0
 408        SB Pro
 409        SB 16
 410        SB32/64/AWE
 411                Configure SB32/64/AWE just like SB16. See lowlevel/README.awe
 412                for information about using the wave table synth.
 413                NOTE! AWE63/Gold and 16/32/AWE "PnP" cards need to be activated
 414                      using isapnptools before they work with OSS/Free.
 415        SB16 compatible cards by other manufacturers than Creative.
 416                You have been fooled since there are _no_ SB16 compatible
 417                cards on the market (as of May 1997). It's likely that your card
 418                is compatible just with SB Pro but there is also a non-SB-
 419                compatible 16 bit mode. Usually it's MSS/WSS but it could also
 420                be a proprietary one like MV Jazz16 or ESS ES688. OPTi
 421                MAD16 chips are very common in so called "SB 16 bit cards"
 422                (try with the MAD16 driver).
 423
 424        ======================================================================
 425        "Supposed to be SB compatible" cards.
 426                Forget the SB compatibility and check for other alternatives
 427                first. The only cards that work with the SB driver in
 428                Linux have been made by Creative Technology (there is at least
 429                one chip on the card with "CREATIVE" printed on it). The
 430                only other SB compatible chips are ESS and Jazz16 chips
 431                (maybe ALSxxx chips too but they probably don't work).
 432                Most other "16 bit SB compatible" cards such as "OPTi/MAD16" or
 433                "Crystal" are _NOT_ SB compatible in Linux.
 434
 435                Practically all sound cards have some kind of SB emulation mode
 436                in addition to their native (16 bit) mode. In most cases this
 437                (8 bit only) SB compatible mode doesn't work with Linux. If
 438                you get it working it may cause problems with games and
 439                applications which require 16 bit audio. Some 16 bit only
 440                applications don't check if the card actually supports 16 bits.
 441                They just dump 16 bit data to a 8 bit card which produces just
 442                noise.
 443
 444                In most cases the 16 bit native mode is supported by Linux.
 445                Use the SB mode with "clones" only if you don't find anything
 446                better from the rest of this doc.
 447        ======================================================================
 448
 449Gravis Ultrasound (GUS)
 450        GUS
 451        GUS + the 16 bit option
 452        GUS MAX
 453        GUS ACE (No MIDI port and audio recording)
 454        GUS PnP (with RAM)
 455
 456MPU-401 and compatibles
 457        The driver works both with the full (intelligent mode) MPU-401
 458        cards (such as MPU IPC-T and MQX-32M) and with the UART only
 459        dumb MIDI ports. MPU-401 is currently the most common MIDI
 460        interface. Most sound cards are compatible with it. However,
 461        don't enable MPU401 mode blindly. Many cards with native support
 462        in the driver have their own MPU401 driver. Enabling the standard one
 463        will cause a conflict with these cards. So check if your card is
 464        in the list of supported cards before enabling MPU401.
 465
 466Windows Sound System (MSS/WSS)
 467        Even when Microsoft has discontinued their own Sound System card 
 468        they managed to make it a standard. MSS compatible cards are based on 
 469        a codec chip which is easily available from at least two manufacturers
 470        (AD1848 by Analog Devices and CS4231/CS4248 by Crystal Semiconductor).
 471        Currently most sound cards are based on one of the MSS compatible codec
 472        chips. The CS4231 is used in the high quality cards such as GUS MAX,
 473        MediaTrix AudioTrix Pro and TB Tropez (GUS MAX is not MSS compatible). 
 474
 475        Having a AD1848, CS4248 or CS4231 codec chip on the card is a good
 476        sign. Even if the card is not MSS compatible, it could be easy to write
 477        support for it. Note also that most MSS compatible cards
 478        require special boot time initialization which may not be present
 479        in the driver. Also, some MSS compatible cards have native support.
 480        Enabling the MSS support with these cards is likely to
 481        cause a conflict. So check if your card is listed in this file before
 482        enabling the MSS support.
 483
 484Yamaha FM synthesizers (OPL2, OPL3 (not OPL3-SA) and OPL4)
 485        Most sound cards have a FM synthesizer chip. The OPL2 is a 2
 486        operator chip used in the original AdLib card. Currently it's used
 487        only in the cheapest (8 bit mono) cards. The OPL3 is a 4 operator 
 488        FM chip which provides better sound quality and/or more available 
 489        voices than the OPL2. The OPL4 is a new chip that has an OPL3 and
 490        a wave table synthesizer packed onto the same chip. The driver supports
 491        just the OPL3 mode directly. Most cards with an OPL4 (like
 492        SM Wave and AudioTrix Pro) support the OPL4 mode using MPU401
 493        emulation. Writing a native OPL4 support is difficult
 494        since Yamaha doesn't give information about their sample ROM chip.
 495
 496        Enable the generic OPL2/OPL3 FM synthesizer support if your
 497        card has a FM chip made by Yamaha. Don't enable it if your card
 498        has a software (TRS) based FM emulator.
 499
 500        ----------------------------------------------------------------
 501        NOTE! OPL3-SA is different chip than the ordinary OPL3. In addition
 502        to the FM synth this chip has also digital audio (WSS) and
 503        MIDI (MPU401) capabilities. Support for OPL3-SA is described below.
 504        ----------------------------------------------------------------
 505
 506Yamaha OPL3-SA1
 507
 508        Yamaha OPL3-SA1 (YMF701) is an audio controller chip used on some
 509        (Intel) motherboards and on cheap sound cards. It should not be
 510        confused with the original OPL3 chip (YMF278) which is entirely
 511        different chip. OPL3-SA1 has support for MSS, MPU401 and SB Pro
 512        (not used in OSS/Free) in addition to the OPL3 FM synth.
 513
 514        There are also chips called OPL3-SA2, OPL3-SA3, ..., OPL3SA-N. They
 515        are PnP chips and will not work with the OPL3-SA1 driver. You should 
 516        use the standard MSS, MPU401 and OPL3 options with these chips and to
 517        activate the card using isapnptools.
 518
 5194Front Technologies SoftOSS
 520
 521        SoftOSS is a software based wave table emulation which works with
 522        any 16 bit stereo sound card. Due to its nature a fast CPU is
 523        required (P133 is minimum). Although SoftOSS does _not_ use MMX
 524        instructions it has proven out that recent processors (which appear
 525        to have MMX) perform significantly better with SoftOSS than earlier
 526        ones. For example a P166MMX beats a PPro200. SoftOSS should not be used
 527        on 486 or 386 machines.
 528
 529        The amount of CPU load caused by SoftOSS can be controlled by
 530        selecting the CONFIG_SOFTOSS_RATE and CONFIG_SOFTOSS_VOICES
 531        parameters properly (they will be prompted by make config). It's
 532        recommended to set CONFIG_SOFTOSS_VOICES to 32. If you have a
 533        P166MMX or faster (PPro200 is not faster) you can set
 534        CONFIG_SOFTOSS_RATE to 44100 (kHz). However with slower systems it
 535        recommended to use sampling rates around 22050 or even 16000 kHz.
 536        Selecting too high values for these parameters may hang your
 537        system when playing MIDI files with hight degree of polyphony
 538        (number of concurrently playing notes). It's also possible to
 539        decrease CONFIG_SOFTOSS_VOICES. This makes it possible to use
 540        higher sampling rates. However using fewer voices decreases
 541        playback quality more than decreasing the sampling rate.
 542
 543        SoftOSS keeps the samples loaded on the system's RAM so much RAM is
 544        required. SoftOSS should never be used on machines with less than 16 MB
 545        of RAM since this is potentially dangerous (you may accidentally run out
 546        of memory which probably crashes the machine). 
 547
 548        SoftOSS implements the wave table API originally designed for GUS. For
 549        this reason all applications designed for GUS should work (at least
 550        after minor modifications). For example gmod/xgmod and playmidi -g are
 551        known to work.
 552
 553        To work SoftOSS will require GUS compatible
 554        patch files to be installed on the system (in /dos/ultrasnd/midi). You
 555        can use the public domain MIDIA patchset available from several ftp
 556        sites.
 557
 558        *********************************************************************
 559        IMPORTANT NOTICE! The original patch set distributed with the Gravis 
 560        Ultrasound card is not in public domain (even though it's available from
 561        some FTP sites). You should contact Voice Crystal (www.voicecrystal.com)
 562        if you like to use these patches with SoftOSS included in OSS/Free.
 563        *********************************************************************
 564
 565PSS based cards (AD1848 + ADSP-2115 + Echo ESC614 ASIC)
 566        Analog Devices and Echo Speech have together defined a sound card
 567        architecture based on the above chips. The DSP chip is used
 568        for emulation of SB Pro, FM and General MIDI/MT32.
 569
 570        There are several cards based on this architecture. The most known
 571        ones are Orchid SW32 and Cardinal DSP16. 
 572
 573        The driver supports downloading DSP algorithms to these cards.
 574
 575        NOTE! You will have to use the "old" config script when configuring
 576        PSS cards.
 577
 578MediaTrix AudioTrix Pro
 579        The ATP card is built around a CS4231 codec and an OPL4 synthesizer
 580        chips. The OPL4 mode is supported by a microcontroller running a
 581        General MIDI emulator. There is also a SB 1.5 compatible playback mode.
 582
 583Ensoniq SoundScape and compatibles
 584        Ensoniq has designed a sound card architecture based on the
 585        OTTO synthesizer chip used in their professional MIDI synthesizers.
 586        Several companies (including Ensoniq, Reveal and Spea) are selling
 587        cards based on this architecture.
 588
 589        NOTE! The SoundScape PnP is not supported by OSS/Free. Ensoniq VIVO and
 590        VIVO90 cards are not compatible with Soundscapes so the Soundscape
 591        driver will not work with them. You may want to use OSS/Linux with these
 592        cards.
 593
 594OPTi MAD16 and Mozart based cards
 595        The Mozart (OAK OTI-601), MAD16 (OPTi 82C928), MAD16 Pro (OPTi 82C929),
 596        OPTi 82C924/82C925 (in _non_ PnP mode) and OPTi 82C930 interface
 597        chips are used in many different sound cards, including some
 598        cards by Reveal miro and Turtle Beach (Tropez). The purpose of these
 599        chips is to connect other audio components to the PC bus. The
 600        interface chip performs address decoding for the other chips.
 601        NOTE! Tropez Plus is not MAD16 but CS4232 based.
 602        NOTE! MAD16 PnP cards (82C924, 82C925, 82C931) are not MAD16 compatible
 603        in the PnP mode. You will have to use them in MSS mode after having
 604        initialized them using isapnptools or DOS. 82C931 probably requires
 605        initialization using DOS/Windows (running isapnptools is not enough).
 606        It's possible to use 82C931 with OSS/Free by jumpering it to non-PnP
 607        mode (provided that the card has a jumper for this). In non-PnP mode
 608        82C931 is compatible with 82C930 and should work with the MAD16 driver
 609        (without need to use isapnptools or DOS to initialize it). All OPTi
 610        chips are supported by OSS/Linux (both in PnP and non-PnP modes).
 611
 612Audio Excel DSP16 
 613        Support for this card was written by Riccardo Faccetti
 614        (riccardo@cdc8g5.cdc.polimi.it). The AEDSP16 driver included in
 615        the lowlevel/ directory. To use it you should enable the
 616        "Additional low level drivers" option.
 617
 618Crystal CS4232 and CS4236 based cards such as AcerMagic S23, TB Tropez _Plus_ and 
 619        many PC motherboards (Compaq, HP, Intel, ...)
 620        CS4232 is a PnP multimedia chip which contains a CS3231A codec,
 621        SB and MPU401 emulations. There is support for OPL3 too.
 622        Unfortunately the MPU401 mode doesn't work (I don't know how to
 623        initialize it). CS4236 is an enhanced (compatible) version of CS4232.
 624        NOTE! Don't ever try to use isapnptools with CS4232 since this will just
 625        freeze your machine (due to chip bugs). If you have problems in getting
 626        CS4232 working you could try initializing it with DOS (CS4232C.EXE) and
 627        then booting Linux using loadlin. CS4232C.EXE loads a secret firmware
 628        patch which is not documented by Crystal.
 629
 630Turtle Beach Maui and Tropez "classic"
 631        This driver version supports sample, patch and program loading commands
 632        described in the Maui/Tropez User's manual. 
 633        There is now full initialization support too. The audio side of
 634        the Tropez is based on the MAD16 chip (see above).
 635        NOTE! Tropez Plus is different card than Tropez "classic" and will not
 636        work fully in Linux. You can get audio features working by configuring
 637        the card as a CS4232 based card (above).
 638
 639
 640Jumpers and software configuration
 641==================================
 642
 643Some of the earliest sound cards were jumper configurable. You have to
 644configure the driver use I/O, IRQ and DMA settings
 645that match the jumpers. Just few 8 bit cards are fully jumper 
 646configurable (SB 1.x/2.x, SB Pro and clones).
 647Some cards made by Aztech have an EEPROM which contains the 
 648config info. These cards behave much like hardware jumpered cards.
 649
 650Most cards have jumper for the base I/O address but other parameters
 651are software configurable. Sometimes there are few other jumpers too.
 652
 653Latest cards are fully software configurable or they are PnP ISA
 654compatible. There are no jumpers on the board.
 655
 656The driver handles software configurable cards automatically. Just configure
 657the driver to use I/O, IRQ and DMA settings which are known to work.
 658You could usually use the same values than with DOS and/or Windows.
 659Using different settings is possible but not recommended since it may cause
 660some trouble (for example when warm booting from an OS to another or
 661when installing new hardware to the machine).
 662
 663Sound driver sets the soft configurable parameters of the card automatically
 664during boot. Usually you don't need to run any extra initialization
 665programs when booting Linux but there are some exceptions. See the
 666card-specific instructions below for more info.
 667
 668The drawback of software configuration is that the driver needs to know
 669how the card must be initialized. It cannot initialize unknown cards
 670even if they are otherwise compatible with some other cards (like SB,
 671MPU401 or Windows Sound System).
 672
 673
 674What if your card was not listed above?
 675=======================================
 676
 677The first thing to do is to look at the major IC chips on the card.
 678Many of the latest sound cards are based on some standard chips. If you
 679are lucky, all of them could be supported by the driver. The most common ones
 680are the OPTi MAD16, Mozart, SoundScape (Ensoniq) and the PSS architectures
 681listed above. Also look at the end of this file for list of unsupported
 682cards and the ones which could be supported later.
 683
 684The last resort is to send _exact_ name and model information of the card
 685to me together with a list of the major IC chips (manufactured, model) to 
 686me. I could then try to check if your card looks like something familiar.
 687
 688There are many more cards in the world than listed above. The first thing to
 689do with these cards is to check if they emulate some other card or interface
 690such as SB, MSS and/or MPU401. In this case there is a chance to get the
 691card to work by booting DOS before starting Linux (boot DOS, hit ctrl-alt-del
 692and boot Linux without hard resetting the machine). In this method the
 693DOS based driver initializes the hardware to use known I/O, IRQ and DMA
 694settings. If sound driver is configured to use the same settings, everything
 695should work OK.
 696
 697
 698Configuring sound driver (with Linux)
 699=====================================
 700
 701The sound driver is currently distributed as part of the Linux kernel. The 
 702files are in /usr/src/linux/drivers/sound/. 
 703
 704****************************************************************************
 705*       ALWAYS USE THE SOUND DRIVER VERSION WHICH IS DISTRIBUTED WITH      *
 706*       THE KERNEL SOURCE PACKAGE YOU ARE USING. SOME ALPHA AND BETA TEST  *
 707*       VERSIONS CAN BE INSTALLED FROM A SEPARATELY DISTRIBUTED PACKAGE    *
 708*       BUT CHECK THAT THE PACKAGE IS NOT MUCH OLDER (OR NEWER) THAN THE   *
 709*       KERNEL YOU ARE USING. IT'S POSSIBLE THAT THE KERNEL/DRIVER         *
 710*       INTERFACE CHANGES BETWEEN KERNEL RELEASES WHICH MAY CAUSE SOME     *
 711*       INCOMPATIBILITY PROBLEMS.                                          *
 712*                                                                          *
 713*       IN CASE YOU INSTALL A SEPARATELY DISTRIBUTED SOUND DRIVER VERSION, *
 714*       BE SURE TO REMOVE OR RENAME THE OLD SOUND DRIVER DIRECTORY BEFORE  *
 715*       INSTALLING THE NEW ONE. LEAVING OLD FILES TO THE SOUND DRIVER      *
 716*       DIRECTORY _WILL_ CAUSE PROBLEMS WHEN THE DRIVER IS USED OR         *
 717*       COMPILED.                                                          *
 718****************************************************************************
 719
 720To configure the driver, run "make config" in the kernel source directory
 721(/usr/src/linux). Answer "y" or "m" to the question about Sound card support
 722(after the questions about mouse, CD-ROM, ftape, etc. support).  Questions
 723about options for sound will then be asked.
 724
 725After configuring the kernel and sound driver and compile the kernel 
 726following instructions in the kernel README.
 727
 728The sound driver configuration dialog
 729-------------------------------------
 730
 731Sound configuration starts by making some yes/no questions. Be careful
 732when answering to these questions since answering y to a question may
 733prevent some later ones from being asked. For example don't answer y to
 734the first question (PAS16) if you don't really have a PAS16. Don't enable
 735more cards than you really need since they just consume memory. Also
 736some drivers (like MPU401) may conflict with your SCSI controller and
 737prevent kernel from booting. If you card was in the list of supported
 738cards (above), please look at the card specific config instructions
 739(later in this file) before starting to configure. Some cards must be
 740configured in way which is not obvious.
 741
 742So here is the beginning of the config dialog. Answer 'y' or 'n' to these
 743questions. The default answer is shown so that (y/n) means 'y' by default and
 744(n/y) means 'n'. To use the default value, just hit ENTER. But be careful
 745since using the default _doesn't_ guarantee anything.
 746
 747Note also that all questions may not be asked. The configuration program
 748may disable some questions depending on the earlier choices. It may also
 749select some options automatically as well.
 750
 751  "ProAudioSpectrum 16 support",
 752        - Answer 'y'_ONLY_ if you have a Pro Audio Spectrum _16_,
 753          Pro Audio Studio 16 or Logitech SoundMan 16 (be sure that
 754          you read the above list correctly). Don't answer 'y' if you
 755          have some other card made by Media Vision or Logitech since they
 756          are not PAS16 compatible.
 757          NOTE! Since 3.5-beta10 you need to enable SB support (next question)
 758          if you want to use the SB emulation of PAS16. It's also possible to
 759          the emulation if you want to use a true SB card together with PAS16
 760          (there is another question about this that is asked later).
 761  "Sound Blaster support",
 762        - Answer 'y' if you have an original SB card made by Creative Labs
 763          or a full 100% hardware compatible clone (like Thunderboard or
 764          SM Games). If your card was in the list of supported cards (above),
 765          please look at the card specific instructions later in this file
 766          before answering this question. For an unknown card you may answer 
 767          'y' if the card claims to be SB compatible.
 768         Enable this option also with PAS16 (changed since v3.5-beta9).
 769
 770         Don't enable SB if you have a MAD16 or Mozart compatible card.
 771
 772  "Generic OPL2/OPL3 FM synthesizer support",
 773        - Answer 'y' if your card has a FM chip made by Yamaha (OPL2/OPL3/OPL4).
 774          Answering 'y' is usually a safe and recommended choice. However some
 775          cards may have software (TSR) FM emulation. Enabling FM support
 776          with these cards may cause trouble. However I don't currently know
 777          such cards.
 778  "Gravis Ultrasound support",
 779        - Answer 'y' if you have GUS or GUS MAX. Answer 'n' if you don't
 780          have GUS since the GUS driver consumes much memory.
 781          Currently I don't have experiences with the GUS ACE so I don't
 782          know what to answer with it.
 783  "MPU-401 support (NOT for SB16)",
 784        - Be careful with this question. The MPU401 interface is supported
 785          by almost any sound card today. However some natively supported cards
 786          have their own driver for MPU401. Enabling the MPU401 option with
 787          these cards will cause a conflict. Also enabling MPU401 on a system
 788          that doesn't really have a MPU401 could cause some trouble. If your
 789          card was in the list of supported cards (above), please look at
 790          the card specific instructions later in this file.
 791
 792          In MOST cases this MPU401 driver should only be used with "true"
 793          MIDI-only MPU401 professional cards. In most other cases there
 794          is another way to get the MPU401 compatible interface of a
 795          sound card to work.
 796          Support for the MPU401 compatible MIDI port of SB16, ESS1688
 797          and MV Jazz16 cards is included in the SB driver. Use it instead
 798          of this separate MPU401 driver with these cards. As well 
 799          Soundscape, PSS and Maui drivers include their own MPU401
 800          options.
 801
 802          It's safe to answer 'y' if you have a true MPU401 MIDI interface
 803          card. 
 804  "6850 UART Midi support",
 805        - It's safe to answer 'n' to this question in all cases. The 6850
 806          UART interface is so rarely used.
 807  "PSS (ECHO-ADI2111) support",
 808        - Answer 'y' only if you have Orchid SW32, Cardinal DSP16 or some
 809          other card based on the PSS chipset (AD1848 codec + ADSP-2115
 810          DSP chip + Echo ESC614 ASIC CHIP).
 811  "16 bit sampling option of GUS (_NOT_ GUS MAX)",
 812        - Answer 'y' if you have installed the 16 bit sampling daughtercard
 813          to your GUS. Answer 'n' if you have GUS MAX. Enabling this option
 814          disables GUS MAX support.
 815  "GUS MAX support",
 816        - Answer 'y' only if you have a GUS MAX.
 817  "Microsoft Sound System support",
 818        - Again think carefully before answering 'y' to this question. It's
 819          safe to answer 'y' in case you have the original Windows Sound 
 820          System card made by Microsoft or Aztech SG 16 Pro (or NX16 Pro).
 821          Also you may answer 'y' in case your card was not listed earlier
 822          in this file. For cards having native support in the driver, consult
 823          the card specific instructions later in this file. Some drivers
 824          have their own MSS support and enabling this option will cause a
 825          conflict. 
 826          Note! The MSS driver permits configuring two DMA channels. This is a
 827          "nonstandard" feature and works only with very few cards (if any).
 828          In most cases the second DMA channel should be disabled or set to
 829          the same channel than the first one. Trying to configure two separate
 830          channels with cards that don't support this feature will prevent
 831          audio (at least recording) from working.
 832  "Ensoniq Soundscape support",
 833        - Answer 'y' if you have a sound card based on the Ensoniq SoundScape
 834          chipset. Such cards are being manufactured at least by Ensoniq,
 835          Spea and Reveal (note that Reveal makes other cards also).  The oldest
 836          cards made by Spea don't work properly with Linux. 
 837          Soundscape PnP as well as Ensoniq VIVO work only with the commercial
 838          OSS/Linux version.
 839  "MediaTrix AudioTrix Pro support",
 840        - Answer 'y' if you have the AudioTrix Pro.
 841  "Support for MAD16 and/or Mozart based cards",
 842        - Answer y if your card has a Mozart (OAK OTI-601) or MAD16
 843          (OPTi 82C928, 82C929, 82C924/82C925 or 82C930) audio interface chip. 
 844          These chips are
 845          currently quite common so it's possible that many no-name cards
 846          have one of them. In addition the MAD16 chip is used in some
 847          cards made by known manufacturers such as Turtle Beach (Tropez),
 848          Reveal (some models) and Diamond (some recent models).
 849          Note OPTi 82C924 and 82C925 are MAD16 compatible only in non PnP
 850          mode (jumper selectable on many cards).
 851  "Support for TB Maui"
 852        - This enables TB Maui specific initialization. Works with TB Maui
 853        and TB Tropez (may not work with Tropez Plus).
 854
 855
 856Then the configuration program asks some y/n questions about the higher
 857level services. It's recommended to answer 'y' to each of these questions.
 858Answer 'n' only if you know you will not need the option.
 859
 860  "MIDI interface support",
 861        - Answering 'n' disables /dev/midi## devices and access to any
 862          MIDI ports using /dev/sequencer and /dev/music. This option
 863          also affects any MPU401 and/or General MIDI compatible devices.
 864  "FM synthesizer (YM3812/OPL-3) support",
 865        - Answer 'y' here.
 866  "/dev/sequencer support",
 867        - Answering 'n' disables /dev/sequencer and /dev/music.
 868
 869Entering the I/O, IRQ and DMA config parameters
 870-----------------------------------------------
 871
 872After the above questions the configuration program prompts for the
 873card specific configuration information. Usually just a set of
 874I/O address, IRQ and DMA numbers are asked. With some cards the program
 875asks for some files to be used during initialization of the card. For example
 876many cards have a DSP chip or microprocessor which must be initialized by
 877downloading a program (microcode) file to the card.
 878
 879Instructions for answering these questions are given in the next section.
 880
 881
 882Card specific information
 883=========================
 884
 885This section gives additional instructions about configuring some cards.
 886Please refer manual of your card for valid I/O, IRQ and DMA numbers. Using
 887the same settings with DOS/Windows and Linux is recommended. Using
 888different values could cause some problems when switching between
 889different operating systems.
 890
 891Sound Blasters (the original ones by Creative)
 892---------------------------------------------
 893
 894NOTE! Check if you have a PnP Sound Blaster (cards sold after summer 1995
 895      are almost certainly PnP ones). With PnP cards you should use isapnptools
 896      to activate them (see above).
 897
 898It's possible to configure these cards to use different I/O, IRQ and
 899DMA settings. Since the possible/default settings have changed between various
 900models, you have to consult manual of your card for the proper ones. It's
 901a good idea to use the same values than with DOS/Windows. With SB and SB Pro
 902it's the only choice. SB16 has software selectable IRQ and DMA channels but
 903using different values with DOS and Linux is likely to cause troubles. The
 904DOS driver is not able to reset the card properly after warm boot from Linux
 905if Linux has used different IRQ or DMA values.
 906
 907The original (steam) Sound Blaster (versions 1.x and 2.x) use always
 908DMA1. There is no way to change it.
 909
 910The SB16 needs two DMA channels. A 8 bit one (1 or 3) is required for
 9118 bit operation and a 16 bit one (5, 6 or 7) for the 16 bit mode. In theory
 912it's possible to use just one (8 bit) DMA channel by answering the 8 bit
 913one when the configuration program asks for the 16 bit one. This may work
 914in some systems but is likely to cause terrible noise on some other systems.
 915
 916It's possible to use two SB16/32/64 at the same time. To do this you should
 917first configure OSS/Free for one card. Then edit local.h manually and define
 918SB2_BASE, SB2_IRQ, SB2_DMA and SB2_DMA2 for the second one. You can't get
 919the OPL3, MIDI and EMU8000 devices of the second card to work. If you are
 920going to use two PnP Sound Blasters, ensure that they are of different model
 921and have different PnP IDs. There is no way to get two cards with the same
 922card ID and serial number to work. The easiest way to check this is trying 
 923if isapnptools can see both cards or just one.
 924
 925NOTE!   Don't enable the SM Games option (asked by the configuration program)
 926        if you are not 101% sure that your card is a Logitech Soundman Games
 927        (not a SM Wave or SM16).
 928
 929SB Clones
 930---------
 931
 932First of all: There are no SB16 clones. There are SB Pro clones with a
 93316 bit mode which is not SB16 compatible. The most likely alternative is that
 934the 16 bit mode means MSS/WSS.
 935
 936There are just a few fully 100% hardware SB or SB Pro compatible cards.
 937I know just Thunderboard and SM Games. Other cards require some kind of
 938hardware initialization before they become SB compatible. Check if your card
 939was listed in the beginning of this file. In this case you should follow
 940instructions for your card later in this file.
 941
 942For other not fully SB clones you may try initialization using DOS in
 943the following way:
 944
 945        - Boot DOS so that the card specific driver gets run.
 946        - Hit ctrl-alt-del (or use loadlin) to boot Linux. Don't
 947          switch off power or press the reset button.
 948        - If you use the same I/O, IRQ and DMA settings in Linux, the
 949          card should work.
 950
 951If your card is both SB and MSS compatible, I recommend using the MSS mode.
 952Most cards of this kind are not able to work in the SB and the MSS mode 
 953simultaneously. Using the MSS mode provides 16 bit recording and playback.
 954
 955ProAudioSpectrum 16 and compatibles
 956-----------------------------------
 957
 958PAS16 has a SB emulation chip which can be used together with the native
 959(16 bit) mode of the card. To enable this emulation you should configure 
 960the driver to have SB support too (this has been changed since version
 9613.5-beta9 of this driver).
 962
 963With current driver versions it's also possible to use PAS16 together with 
 964another SB compatible card. In this case you should configure SB support
 965for the other card and to disable the SB emulation of PAS16 (there is a
 966separate questions about this).
 967
 968With PAS16 you can use two audio device files at the same time. /dev/dsp (and
 969/dev/audio) is connected to the 8/16 bit native codec and the /dev/dsp1 (and
 970/dev/audio1) is connected to the SB emulation (8 bit mono only).
 971
 972Gravis Ultrasound
 973-----------------
 974
 975There are many different revisions of the Ultrasound card (GUS). The
 976earliest ones (pre 3.7) don't have a hardware mixer. With these cards
 977the driver uses a software emulation for synth and pcm playbacks. It's
 978also possible to switch some of the inputs (line in, mic) off by setting
 979mixer volume of the channel level below 10%. For recording you have
 980to select the channel as a recording source and to use volume above 10%.
 981
 982GUS 3.7 has a hardware mixer.
 983
 984GUS MAX and the 16 bit sampling daughtercard have a CS4231 codec chip which 
 985also contains a mixer.
 986
 987Configuring GUS is simple. Just enable the GUS support and GUS MAX or
 988the 16 bit daughtercard if you have them. Note that enabling the daughter
 989card disables GUS MAX driver.
 990
 991NOTE for owners of the 16 bit daughtercard: By default the daughtercard
 992uses /dev/dsp (and /dev/audio). Command "ln -sf /dev/dsp1 /dev/dsp"
 993selects the daughter card as the default device.
 994
 995With just the standard GUS enabled the configuration program prompts
 996for the I/O, IRQ and DMA numbers for the card. Use the same values than
 997with DOS.
 998
 999With the daughter card option enabled you will be prompted for the I/O,
1000IRQ and DMA numbers for the daughter card. You have to use different I/O
1001and DMA values than for the standard GUS. The daughter card permits
1002simultaneous recording and playback. Use /dev/dsp (the daughtercard) for
1003recording and /dev/dsp1 (GUS GF1) for playback.
1004
1005GUS MAX uses the same I/O address and IRQ settings than the original GUS
1006(GUS MAX = GUS + a CS4231 codec). In addition an extra DMA channel may be used.
1007Using two DMA channels permits simultaneous playback using two devices
1008(dev/dsp0 and /dev/dsp1). The second DMA channel is required for
1009full duplex audio.
1010To enable the second DMA channels, give a valid DMA channel when the config
1011program asks for the GUS MAX DMA (entering -1 disables the second DMA).
1012Using 16 bit DMA channels (5,6 or 7) is recommended.
1013
1014If you have problems in recording with GUS MAX, you could try to use
1015just one 8 bit DMA channel. Recording will not work with one DMA
1016channel if it's a 16 bit one.
1017
1018Microphone input of GUS MAX is connected to mixer in little bit nonstandard
1019way. There is actually two microphone volume controls. Normal "mic" controls
1020only recording level. Mixer control "speaker" is used to control volume of
1021microphone signal connected directly to line/speaker out. So just decrease
1022volume of "speaker" if you have problems with microphone feedback.
1023
1024GUS ACE works too but any attempt to record or to use the MIDI port
1025will fail.
1026
1027GUS PnP (with RAM) is partially supported but it needs to be initialized using
1028DOS or isapnptools before starting the driver.
1029
1030MPU401 and Windows Sound System
1031-------------------------------
1032
1033Again. Don't enable these options in case your card is listed
1034somewhere else in this file.
1035
1036Configuring these cards is obvious (or it should be). With MSS
1037you should probably enable the OPL3 synth also since
1038most MSS compatible cards have it. However check that this is true
1039before enabling OPL3.
1040
1041Sound driver supports more than one MPU401 compatible cards at the same time
1042but the config program asks config info for just the first of them.
1043Adding the second or third MPU interfaces must be done manually by
1044editing sound/local.h (after running the config program). Add defines for
1045MPU2_BASE & MPU2_IRQ (and MPU3_BASE & MPU3_IRQ) to the file.
1046
1047CAUTION!
1048
1049The default I/O base of Adaptec AHA-1542 SCSI controller is 0x330 which
1050is also the default of the MPU401 driver. Don't configure the sound driver to
1051use 0x330 as the MPU401 base if you have a AHA1542. The kernel will not boot
1052if you make this mistake.
1053
1054PSS
1055---
1056
1057Even the PSS cards are compatible with SB, MSS and MPU401, you must not
1058enable these options when configuring the driver. The configuration
1059program handles these options itself. (You may use the SB, MPU and MSS options
1060together with PSS if you have another card on the system).
1061
1062The PSS driver enables MSS and MPU401 modes of the card. SB is not enabled 
1063since it doesn't work concurrently with MSS. The driver loads also a
1064DSP algorithm which is used to for the general MIDI emulation. The
1065algorithm file (.ld) is read by the config program and written to a
1066file included when the pss.c is compiled. For this reason the config
1067program asks if you want to download the file. Use the genmidi.ld file
1068distributed with the DOS/Windows drivers of the card (don't use the mt32.ld).
1069With some cards the file is called 'synth.ld'. You must have access to
1070the file when configuring the driver. The easiest way is to mount the DOS
1071partition containing the file with Linux. 
1072
1073It's possible to load your own DSP algorithms and run them with the card.
1074Look at the directory pss_test of snd-util-3.0.tar.gz for more info.
1075
1076AudioTrix Pro
1077-------------
1078
1079You have to enable the OPL3 and SB (not SB Pro or SB16) drivers in addition
1080to the native AudioTrix driver. Don't enable MSS or MPU drivers.
1081
1082Configuring ATP is little bit tricky since it uses so many I/O, IRQ and
1083DMA numbers. Using the same values than with DOS/Win is a good idea. Don't
1084attempt to use the same IRQ or DMA channels twice.
1085
1086The SB mode of ATP is implemented so the ATP driver just enables SB
1087in the proper address. The SB driver handles the rest. You have to configure
1088both the SB driver and the SB mode of ATP to use the same IRQ, DMA and I/O
1089settings.
1090
1091Also the ATP has a microcontroller for the General MIDI emulation (OPL4).
1092For this reason the driver asks for the name of a file containing the
1093microcode (TRXPRO.HEX). This file is usually located in the directory
1094where the DOS drivers were installed. You must have access to this file
1095when configuring the driver. 
1096
1097If you have the effects daughtercard, it must be initialized by running
1098the setfx program of snd-util-3.0.tar.gz package. This step is not required
1099when using the (future) binary distribution version of the driver.
1100
1101Ensoniq SoundScape
1102------------------
1103
1104NOTE!   The new PnP SoundScape is not supported yet. Soundscape compatible
1105        cards made by Reveal don't work with Linux. They use older revision
1106        of the Soundscape chipset which is not fully compatible with
1107        newer cards made by Ensoniq.
1108
1109The SoundScape driver handles initialization of MSS and MPU supports
1110itself so you don't need to enable other drivers than SoundScape
1111(enable also the /dev/dsp, /dev/sequencer and MIDI supports).
1112
1113!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1114!!!!!                                                                   !!!!
1115!!!!! NOTE! Before version 3.5-beta6 there WERE two sets of audio       !!!!
1116!!!!!       device files (/dev/dsp0 and /dev/dsp1). The first one WAS   !!!!
1117!!!!!       used only for card initialization and the second for audio  !!!!
1118!!!!!       purposes. It WAS required to change /dev/dsp (a symlink) to !!!!
1119!!!!!       point to /dev/dsp1.                                         !!!!
1120!!!!!                                                                   !!!!
1121!!!!!       This is not required with OSS versions 3.5-beta6 and later  !!!!
1122!!!!!       since there is now just one audio device file. Please       !!!!
1123!!!!!       change /dev/dsp to point back to /dev/dsp0 if you are       !!!!
1124!!!!!       upgrading from an earlier driver version using              !!!!
1125!!!!!       (cd /dev;rm dsp;ln -s dsp0 dsp).                            !!!!
1126!!!!!                                                                   !!!!
1127!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1128
1129The configuration program asks one DMA channel and two interrupts. One IRQ
1130and one DMA is used by the MSS codec. The second IRQ is required for the
1131MPU401 mode (you have to use different IRQs for both purposes).
1132There were earlier two DMA channels for SoundScape but the current driver
1133version requires just one.
1134
1135The SoundScape card has a Motorola microcontroller which must initialized
1136_after_ boot (the driver doesn't initialize it during boot).
1137The initialization is done by running the 'ssinit' program which is
1138distributed in the snd-util-3.0.tar.gz package. You have to edit two
1139defines in the ssinit.c and then compile the program. You may run ssinit 
1140manually (after each boot) or add it to /etc/rc.d/rc.local.
1141
1142The ssinit program needs the microcode file that comes with the DOS/Windows
1143driver of the card. You will need to use version 1.30.00 or later
1144of the microcode file (sndscape.co0 or sndscape.co1 depending on
1145your card model). THE OLD sndscape.cod WILL NOT WORK. IT WILL HANG YOUR
1146MACHINE. The only way to get the new microcode file is to download
1147and install the DOS/Windows driver from ftp://ftp.ensoniq.com/pub.
1148
1149Then you have to select the proper microcode file to use: soundscape.co0
1150is the right one for most cards and sndscape.co1 is for few (older) cards
1151made by Reveal and/or Spea. The driver has capability to detect the card
1152version during boot. Look at the boot log messages in /var/adm/messages
1153and locate the sound driver initialization message for the SoundScape
1154card. If the driver displays string <Ensoniq Soundscape (old)>, you have
1155an old card and you will need to use sndscape.co1. For other cards use
1156soundscape.co0. New Soundscape revisions such as Elite and PnP use
1157code files with higher numbers (.co2, .co3, etc.).
1158
1159NOTE!   Ensoniq Soundscape VIVO is not compatible with other Soundscape cards.
1160        Currently it's possible to use it in Linux only with OSS/Linux
1161        drivers.
1162
1163Check /var/adm/messages after running ssinit. The driver prints
1164the board version after downloading the microcode file. That version
1165number must match the number in the name of the microcode file (extension).
1166
1167Running ssinit with a wrong version of the sndscape.co? file is not
1168dangerous as long as you don't try to use a file called sndscape.cod.
1169If you have initialized the card using a wrong microcode file (sounds
1170are terrible), just modify ssinit.c to use another microcode file and try
1171again. It's possible to use an earlier version of sndscape.co[01] but it
1172may sound weird.
1173
1174MAD16 (Pro) and Mozart
1175----------------------
1176
1177You need to enable just the MAD16 /Mozart support when configuring
1178the driver. _Don't_ enable SB, MPU401 or MSS. However you will need the
1179/dev/audio, /dev/sequencer and MIDI supports.
1180
1181Mozart and OPTi 82C928 (the original MAD16) chips don't support
1182MPU401 mode so enter just 0 when the configuration program asks the
1183MPU/MIDI I/O base. The MAD16 Pro (OPTi 82C929) and 82C930 chips have MPU401
1184mode.
1185
1186TB Tropez is based on the 82C929 chip. It has two MIDI ports.
1187The one connected to the MAD16 chip is the second one (there is a second
1188MIDI connector/pins somewhere??). If you have not connected the second MIDI
1189port, just disable the MIDI port of MAD16. The 'Maui' compatible synth of
1190Tropez is jumper configurable and not connected to the MAD16 chip (the
1191Maui driver can be used with it).
1192
1193Some MAD16 based cards may cause feedback, whistle or terrible noise if the
1194line3 mixer channel is turned too high. This happens at least with Shuttle
1195Sound System. Current driver versions set volume of line3 low enough so
1196this should not be a problem.
1197
1198If you have a MAD16 card which have an OPL4 (FM + Wave table) synthesizer
1199chip (_not_ an OPL3), you have to append a line containing #define MAD16_OPL4
1200to the file linux/drivers/sound/local.h (after running make config).
1201
1202MAD16 cards having a CS4231 codec support full duplex mode. This mode
1203can be enabled by configuring the card to use two DMA channels. Possible
1204DMA channel pairs are: 0&1, 1&0 and 3&0.
1205
1206NOTE! Cards having an OPTi 82C924/82C925 chip work with OSS/Free only in
1207non-PnP mode (usually jumper selectable). The PnP mode is supported only
1208by OSS/Linux.
1209
1210MV Jazz (ProSonic)
1211------------------
1212
1213The Jazz16 driver is just a hack made to the SB Pro driver. However it works
1214fairly well. You have to enable SB, SB Pro (_not_ SB16) and MPU401 supports
1215when configuring the driver. The configuration program asks later if you
1216want support for MV Jazz16 based cards (after asking SB base address). Answer
1217'y' here and the driver asks the second (16 bit) DMA channel.
1218
1219The Jazz16 driver uses the MPU401 driver in a way which will cause
1220problems if you have another MPU401 compatible card. In this case you must
1221give address of the Jazz16 based MPU401 interface when the config
1222program prompts for the MPU401 information. Then look at the MPU401
1223specific section for instructions about configuring more than one MPU401 cards.
1224
1225Logitech Soundman Wave
1226----------------------
1227
1228Read the above MV Jazz specific instructions first.
1229
1230The Logitech SoundMan Wave (don't confuse this with the SM16 or SM Games) is
1231a MV Jazz based card which has an additional OPL4 based wave table
1232synthesizer. The OPL4 chip is handled by an on board microcontroller
1233which must be initialized during boot. The config program asks if
1234you have a SM Wave immediately after asking the second DMA channel of jazz16.
1235If you answer 'y', the config program will ask name of the file containing
1236code to be loaded to the microcontroller. The file is usually called
1237MIDI0001.BIN and it's located in the DOS/Windows driver directory. The file
1238may also be called as TSUNAMI.BIN or something else (older cards?).
1239
1240The OPL4 synth will be inaccessible without loading the microcontroller code.
1241
1242Also remember to enable SB MPU401 support if you want to use the OPL4 mode.
1243(Don't enable the 'normal' MPU401 device as with some earlier driver
1244versions (pre 3.5-alpha8)).
1245
1246NOTE!   Don't answer 'y' when the driver asks about SM Games support
1247        (the next question after the MIDI0001.BIN name). However
1248        answering 'y' doesn't cause damage your computer so don't panic. 
1249
1250Sound Galaxies
1251--------------
1252
1253There are many different Sound Galaxy cards made by Aztech. The 8 bit
1254ones are fully SB or SB Pro compatible and there should be no problems
1255with them. 
1256
1257The older 16 bit cards (SG Pro16, SG NX Pro16, Nova and Lyra) have
1258an EEPROM chip for storing the configuration data. There is a microcontroller
1259which initializes the card to match the EEPROM settings when the machine
1260is powered on. These cards actually behave just like they have jumpers
1261for all of the settings. Configure driver for MSS, MPU, SB/SB Pro  and OPL3 
1262supports with these cards. 
1263
1264There are some new Sound Galaxies in the market. I have no experience with
1265them so read the card's manual carefully.
1266
1267ESS ES1688 and ES688 'AudioDrive' based cards
1268---------------------------------------------
1269
1270Support for these two ESS chips is embedded in the SB driver.
1271Configure these cards just like SB. Enable the 'SB MPU401 MIDI port'
1272if you want to use MIDI features of ES1688. ES688 doesn't have MPU mode
1273so you don't need to enable it (the driver uses normal SB MIDI automatically
1274with ES688).
1275
1276NOTE! ESS cards are not compatible with MSS/WSS so don't worry if MSS support
1277of OSS doesn't work with it.
1278
1279There are some ES1688/688 based sound cards and (particularly) motherboards
1280which use software configurable I/O port relocation feature of the chip.
1281This ESS proprietary feature is supported only by OSS/Linux.
1282
1283There are ES1688 based cards which use different interrupt pin assignment than
1284recommended by ESS (5, 7, 9/2 and 10). In this case all IRQs don't work.
1285At least a card called (Pearl?) Hypersound 16 supports IRQ 15 but it doesn't
1286work.
1287
1288ES1868 is a PnP chip which is (supposed to be) compatible with ESS1688
1289probably works with OSS/Free after initialization using isapnptools.
1290
1291Reveal cards
1292------------
1293
1294There are several different cards made/marketed by Reveal. Some of them
1295are compatible with SoundScape and some use the MAD16 chip. You may have
1296to look at the card and try to identify its origin.
1297
1298Diamond
1299-------
1300
1301The oldest (Sierra Aria based) sound cards made by Diamond are not supported
1302(they may work if the card is initialized using DOS). The recent (LX?)
1303models are based on the MAD16 chip which is supported by the driver.
1304
1305Audio Excel DSP16
1306-----------------
1307
1308Support for this card is currently not functional. A new driver for it
1309should be available later this year.
1310
1311PCMCIA cards
1312------------
1313
1314Sorry, can't help. Some cards may work and some don't.
1315
1316TI TM4000M notebooks
1317--------------------
1318
1319These computers have a built in sound support based on the Jazz chipset.
1320Look at the instructions for MV Jazz (above). It's also important to note
1321that there is something wrong with the mouse port and sound at least on
1322some TM models. Don't enable the "C&T 82C710 mouse port support" when
1323configuring Linux. Having it enabled is likely to cause mysterious problems
1324and kernel failures when sound is used.
1325
1326miroSOUND
1327---------
1328
1329The miroSOUND PCM1-pro, PCM12 and PCM20 radio has been used
1330successfully. These cards are based on the MAD16, OPL4, and CS4231A chips
1331and everything said in the section about MAD16 cards applies here,
1332too. The only major difference between the PCMxx and other MAD16 cards
1333is that instead of the mixer in the CS4231 codec a separate mixer
1334controlled by an on-board 80C32 microcontroller is used. Control of
1335the mixer takes place via the ACI (miro's audio control interface)
1336protocol that is implemented in a separate lowlevel driver. Make sure
1337you compile this ACI driver together with the normal MAD16 support
1338when you use a miroSOUND PCMxx card. The ACI mixer is controlled by
1339/dev/mixer and the CS4231 mixer by /dev/mixer1 (depends on load
1340time). Only in special cases you want to change something regularly on
1341the CS4231 mixer.
1342
1343The miroSOUND PCM12 and PCM20 radio is capable of full duplex
1344operation (simultaneous PCM replay and recording), which allows you to
1345implement nice real-time signal processing audio effect software and
1346network telephones. The ACI mixer has to be switched into the "solo"
1347mode for duplex operation in order to avoid feedback caused by the
1348mixer (input hears output signal). You can de-/activate this mode
1349through toggleing the record button for the wave controller with an
1350OSS-mixer.
1351
1352The PCM20 contains a radio tuner, which is also controlled by
1353ACI. This radio tuner is supported by the ACI driver together with the
1354miropcm20.o module. Also the 7-band equalizer is integrated
1355(limited by the OSS-design). Development has started and maybe
1356finished for the RDS decoder on this card, too. You will be able to
1357read RadioText, the Programme Service name, Programme TYpe and
1358others. Even the v4l radio module benefits from it with a refined
1359strength value. See aci.[ch] and miropcm20*.[ch] for more details.
1360
1361The following configuration parameters have worked fine for the PCM12
1362in Markus Kuhn's system, many other configurations might work, too:
1363CONFIG_MAD16_BASE=0x530, CONFIG_MAD16_IRQ=11, CONFIG_MAD16_DMA=3, 
1364CONFIG_MAD16_DMA2=0, CONFIG_MAD16_MPU_BASE=0x330, CONFIG_MAD16_MPU_IRQ=10,
1365DSP_BUFFSIZE=65536, SELECTED_SOUND_OPTIONS=0x00281000.
1366
1367Bas van der Linden is using his PCM1-pro with a configuration that
1368differs in: CONFIG_MAD16_IRQ=7, CONFIG_MAD16_DMA=1, CONFIG_MAD16_MPU_IRQ=9
1369
1370Compaq Deskpro XL
1371-----------------
1372
1373The builtin sound hardware of Compaq Deskpro XL is now supported. 
1374You need to configure the driver with MSS and OPL3 supports enabled.
1375In addition you need to manually edit linux/drivers/sound/local.h and
1376to add a line containing "#define DESKPROXL" if you used 
1377make menuconfig/xconfig.
1378
1379Others?
1380-------
1381
1382Since there are so many different sound cards, it's likely that I have 
1383forgotten to mention many of them. Please inform me if you know yet another
1384card which works with Linux, please inform me (or is anybody else
1385willing to maintain a database of supported cards (just like in XF86)?).
1386
1387Cards not supported yet
1388=======================
1389
1390Please check the version of sound driver you are using before 
1391complaining that your card is not supported. It's possible you are 
1392using a driver version which was released months before your card was
1393introduced.
1394
1395First of all, there is an easy way to make most sound cards work with Linux.
1396Just use the DOS based driver to initialize the card to a known state, then use
1397loadlin.exe to boot Linux. If Linux is configured to use the same I/O, IRQ and
1398DMA numbers as DOS, the card could work.
1399(ctrl-alt-del can be used in place of loadlin.exe but it doesn't work with
1400new motherboards). This method works also with all/most PnP sound cards.
1401
1402Don't get fooled with SB compatibility. Most cards are compatible with
1403SB but that may require a TSR which is not possible with Linux. If
1404the card is compatible with MSS, it's a better choice. Some cards
1405don't work in the SB and MSS modes at the same time.
1406
1407Then there are cards which are no longer manufactured and/or which
1408are relatively rarely used (such as the 8 bit ProAudioSpectrum
1409models). It's extremely unlikely that such cards ever get supported.
1410Adding support for a new card requires much work and increases time
1411required in maintaining the driver (some changes need to be done
1412to all low level drivers and be tested too, maybe with multiple
1413operating systems). For this reason I have made a decision to not support
1414obsolete cards. It's possible that someone else makes a separately 
1415distributed driver (diffs) for the card. 
1416
1417Writing a driver for a new card is not possible if there are no 
1418programming information available about the card. If you don't
1419find your new card from this file, look from the home page 
1420(http://www.opensound.com/ossfree). Then please contact
1421manufacturer of the card and ask if they have (or are willing to)
1422released technical details of the card. Do this before contacting me. I
1423can only answer 'no' if there are no programming information available.
1424
1425I have made decision to not accept code based on reverse engineering
1426to the driver. There are three main reasons: First I don't want to break
1427relationships to sound card manufacturers. The second reason is that
1428maintaining and supporting a driver without any specs will be a pain.
1429The third reason is that companies have freedom to refuse selling their
1430products to other than Windows users.
1431
1432Some companies don't give low level technical information about their
1433products to public or at least their require signing a NDA. It's not
1434possible to implement a freeware driver for them. However it's possible
1435that support for such cards become available in the commercial version
1436of this driver (see http://www.4Front-tech.com/oss.html for more info).
1437
1438There are some common audio chipsets that are not supported yet. For example
1439Sierra Aria and IBM Mwave. It's possible that these architectures
1440get some support in future but I can't make any promises. Just look
1441at the home page (http://www.opensound.com/ossfree/)
1442for latest info.
1443
1444Information about unsupported sound cards and chipsets is welcome as well
1445as free copies of sound cards, SDKs and operating systems.
1446
1447If you have any corrections and/or comments, please contact me.
1448
1449Hannu Savolainen
1450hannu@opensound.com
1451
1452home page of OSS/Free: http://www.opensound.com/ossfree
1453
1454home page of commercial OSS
1455(Open Sound System) drivers: http://www.opensound.com/oss.html
1456