Documentation for the OPL3-SA2, SA3, and SAx driver (opl3sa2.o)---------------------------------------------------------------Scott Murray, scott@spiteful.orgJanuary 7, 2001NOTE: All trade-marked terms mentioned below are properties of their      respective owners.Supported Devices-----------------This driver is for PnP soundcards based on the following Yamaha audiocontroller chipsets:YMF711 aka OPL3-SA2YMF715 and YMF719 aka OPL3-SA3Up until recently (December 2000), I'd thought the 719 to be adifferent chipset, the OPL3-SAx.  After an email exhange withYamaha, however, it turns out that the 719 is just a re-badged715, and the chipsets are identical.  The chipset detection codehas been updated to reflect this.Anyways, all of these chipsets implement the following devices:OPL3 FM synthesizerSoundblaster ProMicrosoft/Windows Sound SystemMPU401 MIDI interfaceNote that this driver uses the MSS device, and to my knowledge thesechipsets enforce an either/or situation with the Soundblaster Prodevice and the MSS device.  Since the MSS device has bettercapabilities, I have implemented the driver to use it.Mixer Channels--------------Older versions of this driver (pre-December 2000) had two mixers,an OPL3-SA2 or SA3 mixer and a MSS mixer.  The OPL3-SA[23] mixerdevice contained a superset of mixer channels consisting of its ownchannels and all of the MSS mixer channels.  To simplify the driverconsiderably, and to partition functionality better, the OPL3-SA[23]mixer device now contains has its own specific mixer channels.  Theyare:Volume     - Hardware master volume controlBass       - SA3 only, now supports left and right channelsTreble     - SA3 only, now supports left and right channelsMicrophone - Hardware microphone input volume controlDigital1   - Yamaha 3D enhancement "Wide" mixerAll other mixer channels (e.g. "PCM", "CD", etc.) now have to becontrolled via the "MS Sound System (CS4231)" mixer.  To facilitatethis, the mixer device creation order has been switched so thatthe MSS mixer is created first.  This allows accessing the majorityof the useful mixer channels even via single mixer-aware toolssuch as "aumix".Plug 'n Play------------In previous kernels (2.2.x), some configuration was required toget the driver to talk to the card.  Being the new millennium andall, the 2.4.x kernels now support auto-configuration if ISA PnPsupport is configured in.  Theoretically, the driver even supportshaving more than one card in this case.With the addition of PnP support to the driver, two new parametershave been added to control it:isapnp   - set to 0 to disable ISA PnP card detectionmultiple - set to 0 to disable multiple PnP card detectionOptional Parameters-------------------Recent (December 2000) additions to the driver (based on a patchprovided by Peter Englmaier) are two new parameters:ymode -    Set Yamaha 3D enhancement mode:           0 = Desktop/Normal  5-12 cm speakers           1 = Notebook PC (1) 3 cm speakers           2 = Notebook PC (2) 1.5 cm speakers           3 = Hi-Fi           16-38 cm speakersloopback - Set A/D input source. Useful for echo cancellation:           0 = Mic Right channel (default)           1 = Mono output loopbackThe ymode parameter has been tested and does work.  The loopbackparameter, however, is untested.  Any feedback on its usefulnesswould be appreciated.Manual Configuration--------------------If for some reason you decide not to compile ISA PnP support intoyour kernel, or disabled the driver's usage of it by setting theisapnp parameter as discussed above, then you will need to do somemanual configuration.  There are two ways of doing this.  The mostcommon is to use the isapnptools package to initialize the card, anduse the kernel module form of the sound subsystem and sound drivers.Alternatively, some BIOS's allow manual configuration of installedPnP devices in a BIOS menu, which should allow using the non-modularsound drivers, i.e. built into the kernel.I personally use isapnp and modules, and do not have access to a PnPBIOS machine to test.  If you have such a beast, configuring thedriver to be built into the kernel should just work (thanks to workdone by David Luyer <luyer@ucs.uwa.edu.au>).  You will still needto specify settings, which can be done by adding:opl3sa2=<io>,<irq>,<dma>,<dma2>,<mssio>,<mpuio>to the kernel command line.  For example:opl3sa2=0x370,5,0,1,0x530,0x330If you are instead using the isapnp tools (as most people have beenbefore Linux 2.4.x), follow the directions in their documentation toproduce a configuration file.  Here is the relevant excerpt I used touse for my SA3 card from my isapnp.conf:(CONFIGURE YMH0800/-1 (LD 0# NOTE: IO 0 is for the unused SoundBlaster part of the chipset.(IO 0 (BASE 0x0220))(IO 1 (BASE 0x0530))(IO 2 (BASE 0x0388))(IO 3 (BASE 0x0330))(IO 4 (BASE 0x0370))(INT 0 (IRQ 5 (MODE +E)))(DMA 0 (CHANNEL 0))(DMA 1 (CHANNEL 1))Here, note that:Port  Acceptable Range  Purpose----  ----------------  -------IO 0  0x0220 - 0x0280   SB base address, unused.IO 1  0x0530 - 0x0F48   MSS base addressIO 2  0x0388 - 0x03F8   OPL3 base addressIO 3  0x0300 - 0x0334   MPU base addressIO 4  0x0100 - 0x0FFE   card's own base address for its control I/O portsThe IRQ and DMA values can be any that are considered acceptable for aMSS.  Assuming you've got isapnp all happy, then you should be able todo something like the following (which matches up with the isapnpconfiguration above):modprobe mpu401modprobe ad1848modprobe opl3sa2 io=0x370 mss_io=0x530 mpu_io=0x330 irq=5 dma=0 dma2=1modprobe opl3 io=0x388See the section "Automatic Module Loading" below for how to set up/etc/modprobe.conf to automate this.An important thing to remember that the opl3sa2 module's io argument isfor it's own control port, which handles the card's master mixer forvolume (on all cards), and bass and treble (on SA3 cards).Troubleshooting---------------If all goes well and you see no error messages, you should be able tostart using the sound capabilities of your system.  If you get anerror message while trying to insert the opl3sa2 module, then makesure that the values of the various arguments match what you specifiedin your isapnp configuration file, and that there is no conflict withanother device for an I/O port or interrupt.  Checking the contents of/proc/ioports and /proc/interrupts can be useful to see if you'rebutting heads with another device.If you still cannot get the module to load, look at the contents ofyour system log file, usually /var/log/messages.  If you see themessage "opl3sa2: Unknown Yamaha audio controller version", then youhave a different chipset version than I've encountered so far.  Lookfor all messages in the log file that start with "opl3sa2: " and seeif they provide any clues.  If you do not see the chipset versionmessage, and none of the other messages present in the system log arehelpful, email me some details and I'll try my best to help.Automatic Module Loading------------------------Lastly, if you're using modules and want to set up automatic moduleloading with kmod, the kernel module loader, here is the section Icurrently use in my modprobe.conf file:# Soundalias sound-slot-0 opl3sa2options opl3sa2 io=0x370 mss_io=0x530 mpu_io=0x330 irq=7 dma=0 dma2=3options opl3 io=0x388That's all it currently takes to get an OPL3-SA3 card working on mysystem.  Once again, if you have any other problems, email me at theaddress listed above.Scott