more scheduled OSS driver removal

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

What:  drivers depending on OSS_OBSOLETE_DRIVER

When:  options in 2.6.20, code in 2.6.22

Why:   OSS drivers with ALSA replacements

Who:   Adrian Bunk <bunk@stusta.de>

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

What:	Unused EXPORT_SYMBOL/EXPORT_SYMBOL_GPL exports

	(temporary transition config option provided until then)

	The transition config option will also be removed at the same time.

			Disable PIN 1 of APIC timer

			Can be useful to work around chipset bugs.

	ad1816=		[HW,OSS]

			Format: <io>,<irq>,<dma>,<dma2>

			See also Documentation/sound/oss/AD1816.

	ad1848=		[HW,OSS]

			Format: <io>,<irq>,<dma>,<dma2>,<type>

	adlib=		[HW,OSS]

			Format: <io>

	advansys=	[HW,SCSI]

			See header of drivers/scsi/advansys.c.

	opl3=		[HW,OSS]

			Format: <io>

	opl3sa2=	[HW,OSS] Format:

			<io>,<irq>,<dma>,<dma2>,<mss_io>,<mpu_io>,<ymode>,<loopback>[,<isapnp>,<multiple]

	oprofile.timer=	[HW]

			Use timer interrupt instead of performance counters

Documentation for the AD1816(A) sound driver

============================================

Installation:

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

To get your AD1816(A) based sound card work, you'll have to enable support for

experimental code ("Prompt for development and/or incomplete code/drivers")

and isapnp ("Plug and Play support", "ISA Plug and Play support"). Enable

"Sound card support", "OSS modules support" and "Support for AD1816(A) based

cards (EXPERIMENTAL)" in the sound configuration menu, too. Now build, install

and reboot the new kernel as usual.

Features:

---------

List of features supported by this driver:

- full-duplex support

- supported audio formats: unsigned 8bit, signed 16bit little endian, 

                           signed 16bit big endian, µ-law, A-law

- supported channels: mono and stereo

- supported recording sources: Master, CD, Line, Line1, Line2, Mic

- supports phat 3d stereo circuit (Line 3)

Supported cards:

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

The following cards are known to work with this driver:

- Terratec Base 1 

- Terratec Base 64 

- HP Kayak 

- Acer FX-3D

- SY-1816 

- Highscreen Sound-Boostar 32 Wave 3D

- Highscreen Sound-Boostar 16 

- AVM Apex Pro card 

- (Aztech SC-16 3D) 

- (Newcom SC-16 3D) 

- (Terratec EWS64S) 

Cards listed in brackets are not supported reliable. If you have such a card 

you should add the extra parameter:

  options=1

when loading the ad1816 module via modprobe. 

Troubleshooting:

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

First of all you should check, if the driver has been loaded

properly.

If loading of the driver succeeds, but playback/capture fails, check

if you used the correct values for irq, dma and dma2 when loading the module.

If one of them is wrong you usually get the following error message:

Nov  6 17:06:13 tek01 kernel: Sound: DMA (output) timed out - IRQ/DRQ config error?

If playback/capture is too fast or to slow, you should have a look at

the clock chip of your sound card. The AD1816 was designed for a 33MHz

oscillator, however most sound card manufacturer use slightly

different oscillators as they are cheaper than 33MHz oscillators. If

you have such a card you have to adjust the ad1816_clockfreq parameter

above. For example: For a card using a 32.875MHz oscillator use

ad1816_clockfreq=32875 instead of ad1816_clockfreq=33000.

Updates, bugfixes and bugreports:

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

As the driver is still experimental and under development, you should

watch out for updates.  Updates of the driver are available on the

Internet from one of my home pages:

  http://www.student.informatik.tu-darmstadt.de/~tek/projects/linux.html

or:

  http://www.tu-darmstadt.de/~tek01/projects/linux.html

Bugreports, bugfixes and related questions should be sent via E-Mail to:

  tek@rbg.informatik.tu-darmstadt.de

Thorsten Knabe <tek@rbg.informatik.tu-darmstadt.de>

Christoph Hellwig <hch@infradead.org>

	Last modified: 2000/09/20

=======================================================

Documentation for the NeoMagic 256AV/256ZX sound driver

=======================================================

You're looking at version 1.1 of the driver.  (Woohoo!) It has been

successfully tested against the following laptop models:

	Sony Z505S/Z505SX/Z505DX/Z505RX

	Sony F150, F160, F180, F250, F270, F280, PCG-F26

	Dell Latitude CPi, CPt (various submodels)

There are a few caveats, which is why you should read the entirety of

this document first.

This driver was developed without any support or assistance from

NeoMagic.  There is no warranty, expressed, implied, or otherwise.  It

is free software in the public domain; feel free to use it, sell it,

give it to your best friends, even claim that you wrote it (but why?!)

but don't go whining to me, NeoMagic, Sony, Dell, or anyone else

when it blows up your computer.

Version 1.1 contains a change to try and detect non-AC97 versions of

the hardware, and not install itself appropriately.  It should also

reinitialize the hardware on an APM resume event, assuming that APM

was configured into your kernel.

============

Installation

============

Enable the sound drivers, the OSS sound drivers, and then the NM256

driver.  The NM256 driver *must* be configured as a module (it won't

give you any other choice).

Next, do the usual "make modules" and "make modules_install".

Finally, insmod the soundcore, sound and nm256 modules.

When the nm256 driver module is loaded, you should see a couple of

confirmation messages in the kernel logfile indicating that it found

the device (the device does *not* use any I/O ports or DMA channels).

Now try playing a wav file, futz with the CD-ROM if you have one, etc.

The NM256 is entirely a PCI-based device, and all the necessary

information is automatically obtained from the card.  It can only be

configured as a module in a vain attempt to prevent people from

hurting themselves.  It works correctly if it shares an IRQ with

another device (it normally shares IRQ 9 with the builtin eepro100

ethernet on the Sony Z505 laptops). 

It does not run the card in any sort of compatibility mode. It will

not work on laptops that have the SB16-compatible, AD1848-compatible

or CS4232-compatible codec/mixer; you will want to use the appropriate

compatible OSS driver with these chipsets.  I cannot provide any

assistance with machines using the SB16, AD1848 or CS4232 compatible

versions.  (The driver now attempts to detect the mixer version, and

will refuse to load if it believes the hardware is not

AC97-compatible.)

The sound support is very basic, but it does include simultaneous

playback and record capability.  The mixer support is also quite

simple, although this is in keeping with the rather limited

functionality of the chipset.

There is no hardware synthesizer available, as the Losedows OPL-3 and

MIDI support is done via hardware emulation.

Only three recording devices are available on the Sony: the

microphone, the CD-ROM input, and the volume device (which corresponds

to the stereo output).  (Other devices may be available on other

models of laptops.)  The Z505 series does not have a builtin CD-ROM,

so of course the CD-ROM input doesn't work.  It does work on laptops

with a builtin CD-ROM drive.

The mixer device does not appear to have any tone controls, at least

on the Z505 series.  The mixer module checks for tone controls in the

AC97 mixer, and will enable them if they are available.

==============

Known problems

==============

  * There are known problems with PCMCIA cards and the eepro100 ethernet 

    driver on the Z505S/Z505SX/Z505DX.  Keep reading.

  * There are also potential problems with using a virtual X display, and

    also problems loading the module after the X server has been started. 

    Keep reading.

  * The volume control isn't anywhere near linear.  Sorry.  This will be

    fixed eventually, when I get sufficiently annoyed with it.  (I doubt

    it will ever be fixed now, since I've never gotten sufficiently

    annoyed with it and nobody else seems to care.)

  * There are reports that the CD-ROM volume is very low.  Since I do not

    have a CD-ROM equipped laptop, I cannot test this (it's kinda hard to

    do remotely).

  * Only 8 fixed-rate speeds are supported.  This is mainly a chipset

    limitation.  It may be possible to support other speeds in the future.

  * There is no support for the telephone mixer/codec.  There is support

    for a phonein/phoneout device in the mixer driver;  whether or not 

    it does anything is anyone's guess.  (Reports on this would be

    appreciated.  You'll have to figure out how to get the phone to

    go off-hook before it'll work, tho.)

  * This driver was not written with any cooperation or support from

    NeoMagic.  If you have any questions about this, see their website

    for their official stance on supporting open source drivers.

============

Video memory

============

The NeoMagic sound engine uses a portion of the display memory to hold

the sound buffer.  (Crazy, eh?)  The NeoMagic video BIOS sets up a

special pointer at the top of video RAM to indicate where the top of

the audio buffer should be placed.

At the present time XFree86 is apparently not aware of this.  It will

thus write over either the pointer or the sound buffer with abandon.

(Accelerated-X seems to do a better job here.)

This implies a few things:

  * Sometimes the NM256 driver has to guess at where the buffer 

    should be placed, especially if the module is loaded after the

    X server is started.  It's usually correct, but it will consistently

    fail on the Sony F250.

  * Virtual screens greater than 1024x768x16 under XFree86 are

    problematic on laptops with only 2.5MB of screen RAM. This

    includes all of the 256AV-equipped laptops.  (Virtual displays

    may or may not work on the 256ZX, which has at least 4MB of

    video RAM.)

If you start having problems with random noise being output either

constantly (this is the usual symptom on the F250), or when windows

are moved around (this is the usual symptom when using a virtual

screen), the best fix is to

  * Don't use a virtual frame buffer.

  * Make sure you load the NM256 module before the X server is

    started.

On the F250, it is possible to force the driver to load properly even

after the XFree86 server is started by doing:

	insmod nm256 buffertop=0x25a800

This forces the audio buffers to the correct offset in screen RAM.

One user has reported a similar problem on the Sony F270, although

others apparently aren't seeing any problems.  His suggested command

is

	insmod nm256 buffertop=0x272800

=================

Official WWW site

=================

The official site for the NM256 driver is:

	http://www.uglx.org/sony.html

You should always be able to get the latest version of the driver there,

and the driver will be supported for the foreseeable future.

==============

Z505RX and IDE

==============

There appears to be a problem with the IDE chipset on the Z505RX; one

of the symptoms is that sound playback periodically hangs (when the

disk is accessed).  The user reporting the problem also reported that

enabling all of the IDE chipset workarounds in the kernel solved the

problem, tho obviously only one of them should be needed--if someone

can give me more details I would appreciate it.

==============================

Z505S/Z505SX on-board Ethernet

==============================

If you're using the on-board Ethernet Pro/100 ethernet support on the Z505

series, I strongly encourage you to download the latest eepro100 driver from

Donald Becker's site:

	ftp://cesdis.gsfc.nasa.gov/pub/linux/drivers/test/eepro100.c

There was a reported problem on the Z505SX that if the ethernet

interface is disabled and reenabled while the sound driver is loaded,

the machine would lock up.  I have included a workaround that is

working satisfactorily.  However, you may occasionally see a message

about "Releasing interrupts, over 1000 bad interrupts" which indicates

that the workaround is doing its job.

==================================

PCMCIA and the Z505S/Z505SX/Z505DX

==================================

There is also a known problem with the Sony Z505S and Z505SX hanging

if a PCMCIA card is inserted while the ethernet driver is loaded, or

in some cases if the laptop is suspended.  This is caused by tons of

spurious IRQ 9s, probably generated from the PCMCIA or ACPI bridges.

There is currently no fix for the problem that works in every case.

The only known workarounds are to disable the ethernet interface

before inserting or removing a PCMCIA card, or with some cards

disabling the PCMCIA card before ejecting it will also help the

problem with the laptop hanging when the card is ejected.

One user has reported that setting the tcic's cs_irq to some value

other than 9 (like 11) fixed the problem.  This doesn't work on my

Z505S, however--changing the value causes the cardmgr to stop seeing

card insertions and removals, cards don't seem to work correctly, and

I still get hangs if a card is inserted when the kernel is booted.

Using the latest ethernet driver and pcmcia package allows me to

insert an Adaptec 1480A SlimScsi card without the laptop hanging,

although I still have to shut down the card before ejecting or

powering down the laptop.  However, similar experiments with a DE-660

ethernet card still result in hangs when the card is inserted.  I am

beginning to think that the interrupts are CardBus-related, since the

Adaptec card is a CardBus card, and the DE-660 is not; however, I

don't have any other CardBus cards to test with.

======

Thanks

======

First, I want to thank everyone (except NeoMagic of course) for their

generous support and encouragement.  I'd like to list everyone's name

here that replied during the development phase, but the list is

amazingly long.

I will be rather unfair and single out a few people, however:

	Justin Maurer, for being the first random net.person to try it,

	and for letting me login to his Z505SX to get it working there

	Edi Weitz for trying out several different versions, and giving

	me a lot of useful feedback

	Greg Rumple for letting me login remotely to get the driver 

	functional on the 256ZX, for his assistance on tracking

	down all sorts of random stuff, and for trying out Accel-X

	Zach Brown, for the initial AC97 mixer interface design

	Jeff Garzik, for various helpful suggestions on the AC97

	interface

	"Mr. Bumpy" for feedback on the Z505RX

	Bill Nottingham, for generous assistance in getting the mixer ID

	code working

=================

Previous versions

=================

Versions prior to 0.3 (aka `noname') had problems with weird artifacts

in the output and failed to set the recording rate properly.  These

problems have long since been fixed.

Versions prior to 0.5 had problems with clicks in the output when

anything other than 16-bit stereo sound was being played, and also had

periodic clicks when recording.

Version 0.7 first incorporated support for the NM256ZX chipset, which

is found on some Dell Latitude laptops (the CPt, and apparently

some CPi models as well).  It also included the generic AC97

mixer module.

Version 0.75 renamed all the functions and files with slightly more

generic names.

Note that previous versions of this document claimed that recording was

8-bit only; it actually has been working for 16-bits all along.

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:

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

# 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/modprobe.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 modprobe.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