kernel/linux/Documentation/sound/oss/OPL3-SA2

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