patch-2.4.2 linux/Documentation/sound/OPL3-SA2

• Lines: 264
• Date: Sun Feb 4 10:05:29 2001
• Orig file: v2.4.1/linux/Documentation/sound/OPL3-SA2
• Orig date: Wed May 24 19:28:05 2000

diff -u --recursive --new-file v2.4.1/linux/Documentation/sound/OPL3-SA2 linux/Documentation/sound/OPL3-SA2
@@ -2,22 +2,26 @@
 ---------------------------------------------------------------
 
 Scott Murray, scott@spiteful.org
-January 5, 1999
+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 aka OPL3-SA3
-YMF719 aka OPL3-SAx (?)
+YMF715 and YMF719 aka OPL3-SA3
 
-I'm a little fuzzy on what exactly is classified a SAx, as I've seen
-the label used to refer to the whole 7xx family and as a specific
-identifier for the 719 on my no-name soundcard.  To make matters
-worse, there seem to be several revisions of the 715 chipset.
+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 refkect this.
 
 Anyways, all of these chipsets implement the following devices:
 
@@ -31,75 +35,142 @@
 device and the MSS device.  Since the MSS device has better
 capabilities, I have implemented the driver to use it.
 
-Being PnP cards, some configuration is required.  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.
+
+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 millenium 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:
+           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 speakers
+
+loopback - Set A/D input source. Useful for echo cancellation:
+           0 = Mic Right channel (default)
+           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, try building both the
-MSS driver and this driver into the kernel (appropriately configured,
-of course).  I have received reports of this working, so it should be
-possible for most people with PnP BIOS.  If it does not work for you,
-then email me if you are willing to experiment in an effort to make it
-work.
-
-************************************************************************
-* I have now had two such machines, and I have fixed this to work
-* properly when built into the kernel.  The Toshiba Libretto series, or
-* at least models 70CT and 110CT which I have owned, use a Yamaha
-* OPL3-SAx (OPL3-SA3 according to documentation) sound chip, IRQ 5,
-* IO addresses 220/530/388/330/370 and DMA 1,0 (_not_ 0,1).  All these
-* configuration settings can be gathered by booting another OS which
-* recognizes the card already.
-*
-* I have made things 'just work' for the non-modular case on such
-* machines when configured properly.
-*
-* David Luyer <luyer@ucs.uwa.edu.au>
-************************************************************************
-
-If you are using isapnp, follow the directions in its documentation to
-produce a configuration file.  Here is the relevant excerpt I use for
-my SAx card from my isapnp.conf:
+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 <luyer@ucs.uwa.edu.au>).  You will still need
+to 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,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
 
-# Instead of (IO 0 (BASE 0x0220)), disable SB:
-(IO 0 (BASE 0x0000))
+# 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 7 (MODE +E)))
+(INT 0 (IRQ 5 (MODE +E)))
 (DMA 0 (CHANNEL 0))
-(DMA 1 (CHANNEL 3))
+(DMA 1 (CHANNEL 1))
 
 Here, note that:
 
 Port  Acceptable Range  Purpose
 ----  ----------------  -------
-IO 0  0x0220 - 0x0280   SB base address, I set to 0 just to be safe.
+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 considered acceptable for a
+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):
 
-insmod mpu401
-insmod ad1848
-insmod opl3sa2 io=0x370 mss_io=0x530 mpu_io=0x330 irq=7 dma=0 dma2=3
-insmod opl3 io=0x388
-
-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 and SAx cards).
+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
@@ -112,29 +183,27 @@
 
 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 "Unknown Yamaha audio controller version", then you have a
-different chipset than I've encountered so far.  Look for a line in
-the log file that says "opl3sa2.c: chipset version = <some number>".
-If you want me to add support for your card, send me the number from
-this line and any information you have on the make and chipset of your
-sound card, and I should be able to work up a permanent fix.
-
-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.
+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 char-major-14 opl3sa2
-pre-install opl3sa2 modprobe "-k" "ad1848"
-post-install opl3sa2 modprobe "-k" "opl3"
+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-SAx card working on my
+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.