Subversion Repositories or1k

Documentation for the OPL3-SA2, SA3, and SAx driver (opl3sa2.o)

---------------------------------------------------------------

Scott Murray, scott@spiteful.org

January 7, 2001

NOTE: 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 audio

controller chipsets:

YMF711 aka OPL3-SA2

YMF715 and YMF719 aka OPL3-SA3

Up until recently (December 2000), I'd thought the 719 to be a

different chipset, the OPL3-SAx.  After an email exhange with

Yamaha, however, it turns out that the 719 is just a re-badged

715, and the chipsets are identical.  The chipset detection code

has been updated to reflect this.

Anyways, all of these chipsets implement the following devices:

OPL3 FM synthesizer

Soundblaster Pro

Microsoft/Windows Sound System

MPU401 MIDI interface

Note that this driver uses the MSS device, and to my knowledge these

chipsets enforce an either/or situation with the Soundblaster Pro

device and the MSS device.  Since the MSS device has better

capabilities, 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] mixer

device contained a superset of mixer channels consisting of its own

channels and all of the MSS mixer channels.  To simplify the driver

considerably, and to partition functionality better, the OPL3-SA[23]

mixer device now contains has its own specific mixer channels.  They

are:

Volume     - Hardware master volume control

Bass       - SA3 only, now supports left and right channels

Treble     - SA3 only, now supports left and right channels

Microphone - Hardware microphone input volume control

Digital1   - Yamaha 3D enhancement "Wide" mixer

All other mixer channels (e.g. "PCM", "CD", etc.) now have to be

controlled via the "MS Sound System (CS4231)" mixer.  To facilitate

this, the mixer device creation order has been switched so that

the MSS mixer is created first.  This allows accessing the majority

of the useful mixer channels even via single mixer-aware tools

such as "aumix".

Plug 'n Play

------------

In previous kernels (2.2.x), some configuration was required to

get the driver to talk to the card.  Being the new millennium and

all, the 2.4.x kernels now support auto-configuration if ISA PnP

support is configured in.  Theoretically, the driver even supports

having more than one card in this case.

With the addition of PnP support to the driver, two new parameters

have been added to control it:

isapnp   - set to 0 to disable ISA PnP card detection

multiple - set to 0 to disable multiple PnP card detection

Optional Parameters

-------------------

Recent (December 2000) additions to the driver (based on a patch

provided by Peter Englmaier) are two new parameters:

ymode -    Set Yamaha 3D enhancement mode:

           1 = Notebook PC (1) 3 cm speakers

           2 = Notebook PC (2) 1.5 cm speakers

           3 = Hi-Fi           16-38 cm speakers

loopback - Set A/D input source. Useful for echo cancellation:

           1 = Mono output loopback

The ymode parameter has been tested and does work.  The loopback

parameter, however, is untested.  Any feedback on its usefulness

would be appreciated.

Manual Configuration

--------------------

If for some reason you decide not to compile ISA PnP support into

your kernel, or disabled the driver's usage of it by setting the

isapnp parameter as discussed above, then you will need to do some

manual configuration.  There are two ways of doing this.  The most

common is to use the isapnptools package to initialize the card, and

use the kernel module form of the sound subsystem and sound drivers.

Alternatively, some BIOS's allow manual configuration of installed

PnP devices in a BIOS menu, which should allow using the non-modular

sound drivers, i.e. built into the kernel.

I personally use isapnp and modules, and do not have access to a PnP

BIOS machine to test.  If you have such a beast, configuring the

driver to be built into the kernel should just work (thanks to work

done by David Luyer ).  You will still need

to specify settings, which can be done by adding:

opl3sa2=,,,,,

to the kernel command line.  For example:

opl3sa2=0x370,5,0,1,0x530,0x330

If you are instead using the isapnp tools (as most people have been

before Linux 2.4.x), follow the directions in their documentation to

produce a configuration file.  Here is the relevant excerpt I used to

use 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 address

IO 2  0x0388 - 0x03F8   OPL3 base address

IO 3  0x0300 - 0x0334   MPU base address

IO 4  0x0100 - 0x0FFE   card's own base address for its control I/O ports

The IRQ and DMA values can be any that are considered acceptable for a

MSS.  Assuming you've got isapnp all happy, then you should be able to

do something like the following (which matches up with the isapnp

configuration above):

modprobe mpu401

modprobe ad1848

modprobe opl3sa2 io=0x370 mss_io=0x530 mpu_io=0x330 irq=5 dma=0 dma2=1

modprobe opl3 io=0x388

See the section "Automatic Module Loading" below for how to set up

/etc/modules.conf to automate this.

An important thing to remember that the opl3sa2 module's io argument is

for it's own control port, which handles the card's master mixer for

volume (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 to

start using the sound capabilities of your system.  If you get an

error message while trying to insert the opl3sa2 module, then make

sure that the values of the various arguments match what you specified

in your isapnp configuration file, and that there is no conflict with

another device for an I/O port or interrupt.  Checking the contents of

/proc/ioports and /proc/interrupts can be useful to see if you're

butting heads with another device.

If you still cannot get the module to load, look at the contents of

your system log file, usually /var/log/messages.  If you see the

message "opl3sa2: Unknown Yamaha audio controller version", then you

have a different chipset version than I've encountered so far.  Look

for all messages in the log file that start with "opl3sa2: " and see

if they provide any clues.  If you do not see the chipset version

message, and none of the other messages present in the system log are

helpful, 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 module

loading with kmod, the kernel module loader, here is the section I

currently use in my modules.conf file:

# Sound

alias sound-slot-0 opl3sa2

options opl3sa2 io=0x370 mss_io=0x530 mpu_io=0x330 irq=7 dma=0 dma2=3

options opl3 io=0x388

That's all it currently takes to get an OPL3-SA3 card working on my

system.  Once again, if you have any other problems, email me at the

address listed above.

Scott