Documentation/sound/oss/Maestro

   1         An OSS/Lite Driver for the ESS Maestro family of sound cards
   2
   3                         Zach Brown, December 1999
   4
   5 Driver Status and Availability
   6 ------------------------------
   7
   8 The most recent version of this driver will hopefully always be available at
   9         http://www.zabbo.net/maestro/
  10
  11 I will try and maintain the most recent stable version of the driver
  12 in both the stable and development kernel lines.
  13
  14 ESS Maestro Chip Family
  15 -----------------------
  16
  17 There are 3 main variants of the ESS Maestro PCI sound chip.  The first
  18 is the Maestro 1.  It was originally produced by Platform Tech as the
  19 'AGOGO'.  It can be recognized by Platform Tech's PCI ID 0x1285 with
  20 0x0100 as the device ID.  It was put on some sound boards and a few laptops.
  21 ESS bought the design and cleaned it up as the Maestro 2.  This starts
  22 their marking with the ESS vendor ID 0x125D and the 'year' device IDs.
  23 The Maestro 2 claims 0x1968 while the Maestro 2e has 0x1978.
  24
  25 The various families of Maestro are mostly identical as far as this
  26 driver is concerned.  It doesn't touch the DSP parts that differ (though
  27 it could for FM synthesis).
  28
  29 Driver OSS Behavior
  30 --------------------
  31
  32 This OSS driver exports /dev/mixer and /dev/dsp to applications, which
  33 mostly adhere to the OSS spec.   This driver doesn't register itself
  34 with /dev/sndstat, so don't expect information to appear there.
  35
  36 The /dev/dsp device exported behaves almost as expected.  Playback is
  37 supported in all the various lovely formats.  8/16bit stereo/mono from
  38 8khz to 48khz, and mmap()ing for playback behaves.  Capture/recording
  39 is limited due to oddities with the Maestro hardware.  One can only
  40 record in 16bit stereo.  For recording the maestro uses non interleaved
  41 stereo buffers so that mmap()ing the incoming data does not result in
  42 a ring buffer of LRLR data.  mmap()ing of the read buffers is therefore
  43 disallowed until this can be cleaned up.
  44
  45 /dev/mixer is an interface to the AC'97 codec on the Maestro.  It is
  46 worth noting that there are a variety of AC'97s that can be wired to
  47 the Maestro.  Which is used is entirely up to the hardware implementor.
  48 This should only be visible to the user by the presence, or lack, of
  49 'Bass' and 'Treble' sliders in the mixer.  Not all AC'97s have them.
  50
  51 The driver doesn't support MIDI or FM playback at the moment.  Typically
  52 the Maestro is wired to an MPU MIDI chip, but some hardware implementations
  53 don't.  We need to assemble a white list of hardware implementations that
  54 have MIDI wired properly before we can claim to support it safely.
  55
  56 Compiling and Installing
  57 ------------------------
  58
  59 With the drivers inclusion into the kernel, compiling and installing
  60 is the same as most OSS/Lite modular sound drivers.  Compilation
  61 of the driver is enabled through the CONFIG_SOUND_MAESTRO variable
  62 in the config system.
  63
  64 It may be modular or statically linked.  If it is modular it should be
  65 installed with the rest of the modules for the kernel on the system.
  66 Typically this will be in /lib/modules/ somewhere.  'alias sound maestro'
  67 should also be added to your module configs (typically /etc/conf.modules)
  68 if you're using modular OSS/Lite sound and want to default to using a
  69 maestro chip.
  70
  71 As this is a PCI device, the module does not need to be informed of
  72 any IO or IRQ resources it should use, it devines these from the
  73 system.  Sometimes, on sucky PCs, the BIOS fails to allocated resources
  74 for the maestro.  This will result in a message like:
  75         maestro: PCI subsystem reports IRQ 0, this might not be correct.
  76 from the kernel.  Should this happen the sound chip most likely will
  77 not operate correctly.  To solve this one has to dig through their BIOS
  78 (typically entered by hitting a hot key at boot time) and figure out
  79 what magic needs to happen so that the BIOS will reward the maestro with
  80 an IRQ.  This operation is incredibly system specific, so you're on your
  81 own.  Sometimes the magic lies in 'PNP Capable Operating System' settings.
  82
  83 There are very few options to the driver.  One is 'debug' which will
  84 tell the driver to print minimal debugging information as it runs.  This
  85 can be collected with 'dmesg' or through the klogd daemon.
  86
  87 The other, more interesting option, is 'dsps_order'.  Typically at
  88 install time the driver will only register one available /dev/dsp device
  89 for its use.  The 'dsps_order' module parameter allows for more devices
  90 to be allocated, as a power of two.  Up to 4 devices can be registered
  91 ( dsps_order=2 ).  These devices act as fully distinct units and use
  92 separate channels in the maestro.
  93
  94 Power Management
  95 ----------------
  96
  97 As of version 0.14, this driver has a minimal understanding of PCI
  98 Power Management.  If it finds a valid power management capability
  99 on the PCI device it will attempt to use the power management
 100 functions of the maestro.  It will only do this on Maestro 2Es and
 101 only on machines that are known to function well.  You can
 102 force the use of power management by setting the 'use_pm' module
 103 option to 1, or can disable it entirely by setting it to 0.
 104
 105 When using power management, the driver does a few things
 106 differently.  It will keep the chip in a lower power mode
 107 when the module is inserted but /dev/dsp is not open.  This
 108 allows the mixer to function but turns off the clocks
 109 on other parts of the chip.  When /dev/dsp is opened the chip
 110 is brought into full power mode, and brought back down
 111 when it is closed.  It also powers down the chip entirely
 112 when the module is removed or the machine is shutdown.  This
 113 can have nonobvious consequences.  CD audio may not work
 114 after a power managing driver is removed.  Also, software that
 115 doesn't understand power management may not be able to talk
 116 to the powered down chip until the machine goes through a hard
 117 reboot to bring it back.
 118
 119 .. more details ..
 120 ------------------
 121
 122 drivers/sound/maestro.c contains comments that hopefully explain
 123 the maestro implementation.