Documentation/sound/oss/Maestro

	An OSS/Lite Driver for the ESS Maestro family of sound cards

			Zach Brown, December 1999

Driver 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 driver
in both the stable and development kernel lines.

ESS Maestro Chip Family
-----------------------

There are 3 main variants of the ESS Maestro PCI sound chip.  The first
is the Maestro 1.  It was originally produced by Platform Tech as the
'AGOGO'.  It can be recognized by Platform Tech's PCI ID 0x1285 with
0x0100 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 starts
their 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 (though
it could for FM synthesis).

Driver OSS Behavior
--------------------

This OSS driver exports /dev/mixer and /dev/dsp to applications, which
mostly adhere to the OSS spec.   This driver doesn't register itself
with /dev/sndstat, so don't expect information to appear there.

The /dev/dsp device exported behaves almost as expected.  Playback is
supported in all the various lovely formats.  8/16bit stereo/mono from
8khz to 48khz, and mmap()ing for playback behaves.  Capture/recording
is limited due to oddities with the Maestro hardware.  One can only
record in 16bit stereo.  For recording the maestro uses non interleaved
stereo buffers so that mmap()ing the incoming data does not result in
a ring buffer of LRLR data.  mmap()ing of the read buffers is therefore
disallowed until this can be cleaned up.

/dev/mixer is an interface to the AC'97 codec on the Maestro.  It is
worth noting that there are a variety of AC'97s that can be wired to
the 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.  Typically
the Maestro is wired to an MPU MIDI chip, but some hardware implementations
don't.  We need to assemble a white list of hardware implementations that
have MIDI wired properly before we can claim to support it safely.

Compiling and Installing
------------------------

With the drivers inclusion into the kernel, compiling and installing
is the same as most OSS/Lite modular sound drivers.  Compilation
of the driver is enabled through the CONFIG_SOUND_MAESTRO variable
in the config system.  

It may be modular or statically linked.  If it is modular it should be
installed 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 a
maestro chip.

As this is a PCI device, the module does not need to be informed of
any IO or IRQ resources it should use, it devines these from the
system.  Sometimes, on sucky PCs, the BIOS fails to allocated resources
for 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 will
not operate correctly.  To solve this one has to dig through their BIOS
(typically entered by hitting a hot key at boot time) and figure out
what magic needs to happen so that the BIOS will reward the maestro with
an IRQ.  This operation is incredibly system specific, so you're on your
own.  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.  This
can be collected with 'dmesg' or through the klogd daemon.

The other, more interesting option, is 'dsps_order'.  Typically at
install time the driver will only register one available /dev/dsp device
for its use.  The 'dsps_order' module parameter allows for more devices
to 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 use
separate channels in the maestro.

Power Management
----------------

As of version 0.14, this driver has a minimal understanding of PCI
Power Management.  If it finds a valid power management capability
on the PCI device it will attempt to use the power management
functions of the maestro.  It will only do this on Maestro 2Es and
only on machines that are known to function well.  You can
force the use of power management by setting the 'use_pm' module
option to 1, or can disable it entirely by setting it to 0.

When using power management, the driver does a few things
differently.  It will keep the chip in a lower power mode
when the module is inserted but /dev/dsp is not open.  This
allows the mixer to function but turns off the clocks
on other parts of the chip.  When /dev/dsp is opened the chip
is brought into full power mode, and brought back down
when it is closed.  It also powers down the chip entirely
when the module is removed or the machine is shutdown.  This
can have nonobvious consequences.  CD audio may not work
after a power managing driver is removed.  Also, software that
doesn't understand power management may not be able to talk
to the powered down chip until the machine goes through a hard
reboot to bring it back.

.. more details ..
------------------

drivers/sound/maestro.c contains comments that hopefully explain
the maestro implementation.