1Documentation for the OPL3-SA2, SA3, and SAx driver (opl3sa2.o) 2--------------------------------------------------------------- 3 4Scott Murray, scott@spiteful.org 5January 7, 2001 6 7NOTE: All trade-marked terms mentioned below are properties of their 8 respective owners. 9 10 11Supported Devices 12----------------- 13 14This driver is for PnP soundcards based on the following Yamaha audio 15controller chipsets: 16 17YMF711 aka OPL3-SA2 18YMF715 and YMF719 aka OPL3-SA3 19 20Up until recently (December 2000), I'd thought the 719 to be a 21different chipset, the OPL3-SAx. After an email exhange with 22Yamaha, however, it turns out that the 719 is just a re-badged 23715, and the chipsets are identical. The chipset detection code 24has been updated to reflect this. 25 26Anyways, all of these chipsets implement the following devices: 27 28OPL3 FM synthesizer 29Soundblaster Pro 30Microsoft/Windows Sound System 31MPU401 MIDI interface 32 33Note that this driver uses the MSS device, and to my knowledge these 34chipsets enforce an either/or situation with the Soundblaster Pro 35device and the MSS device. Since the MSS device has better 36capabilities, I have implemented the driver to use it. 37 38 39Mixer Channels 40-------------- 41 42Older versions of this driver (pre-December 2000) had two mixers, 43an OPL3-SA2 or SA3 mixer and a MSS mixer. The OPL3-SA[23] mixer 44device contained a superset of mixer channels consisting of its own 45channels and all of the MSS mixer channels. To simplify the driver 46considerably, and to partition functionality better, the OPL3-SA[23] 47mixer device now contains has its own specific mixer channels. They 48are: 49 50Volume - Hardware master volume control 51Bass - SA3 only, now supports left and right channels 52Treble - SA3 only, now supports left and right channels 53Microphone - Hardware microphone input volume control 54Digital1 - Yamaha 3D enhancement "Wide" mixer 55 56All other mixer channels (e.g. "PCM", "CD", etc.) now have to be 57controlled via the "MS Sound System (CS4231)" mixer. To facilitate 58this, the mixer device creation order has been switched so that 59the MSS mixer is created first. This allows accessing the majority 60of the useful mixer channels even via single mixer-aware tools 61such as "aumix". 62 63 64Plug 'n Play 65------------ 66 67In previous kernels (2.2.x), some configuration was required to 68get the driver to talk to the card. Being the new millennium and 69all, the 2.4.x kernels now support auto-configuration if ISA PnP 70support is configured in. Theoretically, the driver even supports 71having more than one card in this case. 72 73With the addition of PnP support to the driver, two new parameters 74have been added to control it: 75 76isapnp - set to 0 to disable ISA PnP card detection 77 78multiple - set to 0 to disable multiple PnP card detection 79 80 81Optional Parameters 82------------------- 83 84Recent (December 2000) additions to the driver (based on a patch 85provided by Peter Englmaier) are two new parameters: 86 87ymode - Set Yamaha 3D enhancement mode: 88 0 = Desktop/Normal 5-12 cm speakers 89 1 = Notebook PC (1) 3 cm speakers 90 2 = Notebook PC (2) 1.5 cm speakers 91 3 = Hi-Fi 16-38 cm speakers 92 93loopback - Set A/D input source. Useful for echo cancellation: 94 0 = Mic Right channel (default) 95 1 = Mono output loopback 96 97The ymode parameter has been tested and does work. The loopback 98parameter, however, is untested. Any feedback on its usefulness 99would be appreciated. 100 101 102Manual Configuration 103-------------------- 104 105If for some reason you decide not to compile ISA PnP support into 106your kernel, or disabled the driver's usage of it by setting the 107isapnp parameter as discussed above, then you will need to do some 108manual configuration. There are two ways of doing this. The most 109common is to use the isapnptools package to initialize the card, and 110use the kernel module form of the sound subsystem and sound drivers. 111Alternatively, some BIOS's allow manual configuration of installed 112PnP devices in a BIOS menu, which should allow using the non-modular 113sound drivers, i.e. built into the kernel. 114 115I personally use isapnp and modules, and do not have access to a PnP 116BIOS machine to test. If you have such a beast, configuring the 117driver to be built into the kernel should just work (thanks to work 118done by David Luyer <luyer@ucs.uwa.edu.au>). You will still need 119to specify settings, which can be done by adding: 120 121opl3sa2=<io>,<irq>,<dma>,<dma2>,<mssio>,<mpuio> 122 123to the kernel command line. For example: 124 125opl3sa2=0x370,5,0,1,0x530,0x330 126 127If you are instead using the isapnp tools (as most people have been 128before Linux 2.4.x), follow the directions in their documentation to 129produce a configuration file. Here is the relevant excerpt I used to 130use for my SA3 card from my isapnp.conf: 131 132(CONFIGURE YMH0800/-1 (LD 0 133 134# NOTE: IO 0 is for the unused SoundBlaster part of the chipset. 135(IO 0 (BASE 0x0220)) 136(IO 1 (BASE 0x0530)) 137(IO 2 (BASE 0x0388)) 138(IO 3 (BASE 0x0330)) 139(IO 4 (BASE 0x0370)) 140(INT 0 (IRQ 5 (MODE +E))) 141(DMA 0 (CHANNEL 0)) 142(DMA 1 (CHANNEL 1)) 143 144Here, note that: 145 146Port Acceptable Range Purpose 147---- ---------------- ------- 148IO 0 0x0220 - 0x0280 SB base address, unused. 149IO 1 0x0530 - 0x0F48 MSS base address 150IO 2 0x0388 - 0x03F8 OPL3 base address 151IO 3 0x0300 - 0x0334 MPU base address 152IO 4 0x0100 - 0x0FFE card's own base address for its control I/O ports 153 154The IRQ and DMA values can be any that are considered acceptable for a 155MSS. Assuming you've got isapnp all happy, then you should be able to 156do something like the following (which matches up with the isapnp 157configuration above): 158 159modprobe mpu401 160modprobe ad1848 161modprobe opl3sa2 io=0x370 mss_io=0x530 mpu_io=0x330 irq=5 dma=0 dma2=1 162modprobe opl3 io=0x388 163 164See the section "Automatic Module Loading" below for how to set up 165/etc/modprobe.conf to automate this. 166 167An important thing to remember that the opl3sa2 module's io argument is 168for it's own control port, which handles the card's master mixer for 169volume (on all cards), and bass and treble (on SA3 cards). 170 171 172Troubleshooting 173--------------- 174 175If all goes well and you see no error messages, you should be able to 176start using the sound capabilities of your system. If you get an 177error message while trying to insert the opl3sa2 module, then make 178sure that the values of the various arguments match what you specified 179in your isapnp configuration file, and that there is no conflict with 180another device for an I/O port or interrupt. Checking the contents of 181/proc/ioports and /proc/interrupts can be useful to see if you're 182butting heads with another device. 183 184If you still cannot get the module to load, look at the contents of 185your system log file, usually /var/log/messages. If you see the 186message "opl3sa2: Unknown Yamaha audio controller version", then you 187have a different chipset version than I've encountered so far. Look 188for all messages in the log file that start with "opl3sa2: " and see 189if they provide any clues. If you do not see the chipset version 190message, and none of the other messages present in the system log are 191helpful, email me some details and I'll try my best to help. 192 193 194Automatic Module Loading 195------------------------ 196 197Lastly, if you're using modules and want to set up automatic module 198loading with kmod, the kernel module loader, here is the section I 199currently use in my modprobe.conf file: 200 201# Sound 202alias sound-slot-0 opl3sa2 203options opl3sa2 io=0x370 mss_io=0x530 mpu_io=0x330 irq=7 dma=0 dma2=3 204options opl3 io=0x388 205 206That's all it currently takes to get an OPL3-SA3 card working on my 207system. Once again, if you have any other problems, email me at the 208address listed above. 209 210Scott 211