Linux-2.6.12-rc2
[linux-3.10.git] / 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.