An OSS/Lite Driver for the ESS Maestro family of sound cards			Zach Brown, December 1999Driver Status and Availability------------------------------The most recent version of this driver will hopefully always be available at	http://www.zabbo.net/maestro/I will try and maintain the most recent stable version of the driverin both the stable and development kernel lines.ESS Maestro Chip Family-----------------------There are 3 main variants of the ESS Maestro PCI sound chip.  The firstis the Maestro 1.  It was originally produced by Platform Tech as the'AGOGO'.  It can be recognized by Platform Tech's PCI ID 0x1285 with0x0100 as the device ID.  It was put on some sound boards and a few laptops.  ESS bought the design and cleaned it up as the Maestro 2.  This startstheir marking with the ESS vendor ID 0x125D and the 'year' device IDs.The Maestro 2 claims 0x1968 while the Maestro 2e has 0x1978.The various families of Maestro are mostly identical as far as this driver is concerned.  It doesn't touch the DSP parts that differ (thoughit could for FM synthesis).Driver OSS Behavior--------------------This OSS driver exports /dev/mixer and /dev/dsp to applications, whichmostly adhere to the OSS spec.   This driver doesn't register itselfwith /dev/sndstat, so don't expect information to appear there.The /dev/dsp device exported behaves almost as expected.  Playback issupported in all the various lovely formats.  8/16bit stereo/mono from8khz to 48khz, and mmap()ing for playback behaves.  Capture/recordingis limited due to oddities with the Maestro hardware.  One can onlyrecord in 16bit stereo.  For recording the maestro uses non interleavedstereo buffers so that mmap()ing the incoming data does not result ina ring buffer of LRLR data.  mmap()ing of the read buffers is thereforedisallowed until this can be cleaned up./dev/mixer is an interface to the AC'97 codec on the Maestro.  It isworth noting that there are a variety of AC'97s that can be wired tothe Maestro.  Which is used is entirely up to the hardware implementor.This should only be visible to the user by the presence, or lack, of'Bass' and 'Treble' sliders in the mixer.  Not all AC'97s have them.The driver doesn't support MIDI or FM playback at the moment.  Typicallythe Maestro is wired to an MPU MIDI chip, but some hardware implementationsdon't.  We need to assemble a white list of hardware implementations thathave MIDI wired properly before we can claim to support it safely.Compiling and Installing------------------------With the drivers inclusion into the kernel, compiling and installingis the same as most OSS/Lite modular sound drivers.  Compilationof the driver is enabled through the CONFIG_SOUND_MAESTRO variablein the config system.  It may be modular or statically linked.  If it is modular it should beinstalled with the rest of the modules for the kernel on the system.Typically this will be in /lib/modules/ somewhere.  'alias sound maestro'should also be added to your module configs (typically /etc/conf.modules)if you're using modular OSS/Lite sound and want to default to using amaestro chip.As this is a PCI device, the module does not need to be informed ofany IO or IRQ resources it should use, it devines these from thesystem.  Sometimes, on sucky PCs, the BIOS fails to allocated resourcesfor the maestro.  This will result in a message like:	maestro: PCI subsystem reports IRQ 0, this might not be correct.from the kernel.  Should this happen the sound chip most likely willnot operate correctly.  To solve this one has to dig through their BIOS(typically entered by hitting a hot key at boot time) and figure outwhat magic needs to happen so that the BIOS will reward the maestro withan IRQ.  This operation is incredibly system specific, so you're on yourown.  Sometimes the magic lies in 'PNP Capable Operating System' settings.There are very few options to the driver.  One is 'debug' which will tell the driver to print minimal debugging information as it runs.  Thiscan be collected with 'dmesg' or through the klogd daemon.The other, more interesting option, is 'dsps_order'.  Typically atinstall time the driver will only register one available /dev/dsp devicefor its use.  The 'dsps_order' module parameter allows for more devicesto be allocated, as a power of two.  Up to 4 devices can be registered( dsps_order=2 ).  These devices act as fully distinct units and useseparate channels in the maestro.Power Management----------------As of version 0.14, this driver has a minimal understanding of PCIPower Management.  If it finds a valid power management capabilityon the PCI device it will attempt to use the power managementfunctions of the maestro.  It will only do this on Maestro 2Es andonly on machines that are known to function well.  You canforce the use of power management by setting the 'use_pm' moduleoption to 1, or can disable it entirely by setting it to 0.When using power management, the driver does a few thingsdifferently.  It will keep the chip in a lower power modewhen the module is inserted but /dev/dsp is not open.  Thisallows the mixer to function but turns off the clockson other parts of the chip.  When /dev/dsp is opened the chipis brought into full power mode, and brought back downwhen it is closed.  It also powers down the chip entirelywhen the module is removed or the machine is shutdown.  Thiscan have nonobvious consequences.  CD audio may not workafter a power managing driver is removed.  Also, software thatdoesn't understand power management may not be able to talkto the powered down chip until the machine goes through a hardreboot to bring it back... more details ..------------------drivers/sound/maestro.c contains comments that hopefully explainthe maestro implementation.