Installation Instruction for emu-tools-0.9.4 
Readme v1.2 (January 26, 2002)
--------------------------------------------


The emu-tools are work with the emu10k1 driver include in the kernel (as 
of 2.4.8). The latest version of both the driver and the emu-tools are 

available at: http://sourceforge.net/projects/emu10k1

COMPILATION
===========

untar this package, enter the directory and make. i.e. :

	tar zxfv emu-tools-XXX.tar.gz
	cd emu-tools-XXX.tar.gz
	make

INSTALLATION
============

As root type:

	make install


This will install 2 command-line executable: 'emu-dspmgr' and 'emu-config'


emu-dspmgr - A tool for configuring the cards dsp patch management system
             (e.g for loading "effects", or routing an input to an output)

emu-config - A tool for configuring the card (e.g. toggling the analog/digital
             output, selecting recording modes, etc)

Also, several ".bin" dsp patches will be installed in /usr/local/share/emu10k1/
you can load these patches using emu-dspmgr. A description of each effect
is provided in  /usr/local/share/emu10k1/README


For more details on using the above tools, see the man pages. 



GETTING STARTED
===============


The driver may need to be configured appropriately for your card/speaker combo.
The driver should work out-of-the-box for most situations unless the following 
apply:

-You want bass/treble control
-You have a '5.1' card with digital speakers
-You want to use AC3 Pass-through
-You're the type of person who likes to learn and customize things.
-You want to enable an input on your Live-drive or digital add-on card


The basics:
----------

If you don't want to bother to learn how to use the emu tools, you are
encouraged to try out "emu-script". It'll be automatically installed to
'/usr/local/etc/'. 

You'll need to set some configurations variables in 
'/usr/local/etc/emu10k1.conf' according to your setup. 

Then, test out the script by running it directly, i.e. type:
 /usr/local/etc/emu-script



To have it run automatically at module load, insert the following line in
your /etc/modules.conf:

post-install emu10k1 /usr/local/etc/emu-script

Or, if you want to have it save/restore mixer volume settings:

post-install emu10k1 /usr/local/etc/emu-script restore
pre-remove emu10k1 /usr/local/etc/emu-script save



The Gory Details:
-----------------


The emu10k1 is really a dsp processor. It does not do any effects on it's own,
nor does it route sound from input to output. We had to write dsp code to do that 
ourselves. 


(before anyone ask, no there's no data-sheet/Eng doc available on the 
emu10k1 or SBLive, see docs/manual.txt for a list of other references)


Routing inputs to outputs is the most simplest of operation. A table describing 
the available inputs and outputs is shown below:

Inputs:
  Pcm L 	-	PCM audio coming from host CPU (/dev/dsp)
  Pcm R
  fx2		-	Unused
  fx3		-	Unused
  Pcm1 L	-	PCM audio from /dev/dsp1
  Pcm1 R
  fx6		-	Unused
  fx7		-	Unused
  fx8		-	First channel in multiplayback PCM
  fx9		-	second channel
  fx10		-	third	
  fx11		-	fourth
  fx12		-	fifth	
  fx13		-	Last channel multiplayback PCM
  fx14		-	Unused	
  fx15		-	Unused
  Analog L	-	Analog inputs (mic/line-in/video/analog-CD)
  Analog R	-	   (the source is the record source selected via oss mixer)
  CD-Spdif L	-	Digital CD
  CD-Spdif R
  in2l		-	Unknown
  in2r
  Opt. Spdif L	-	Optical Spdif inputs found on the Live Drive
  Opt. Spdif R
  Line2/Mic2 L	-	Another input found on the  Live drive
  Line2/Mic2 R
  RCA Spdif L	-	Another Spdif input on Live drive
  RCA Spdif R
  RCA Aux L	-	Yet another input on Live drive
  RCA Aux R
  in7l		-	unknown
  in7r



Outputs:
  Front L	-	Analog Front out (sends to AC97 codec analog mixer)
  Front R
  Digital L	-	Digital Front out
  Digital R	
  Digital Center -	Digital Center on SBLive-5.1		
  Digital LFE	-	Digital LFE on SBLive-5.1
  Phones L	-	Headphones output on live-drive
  Phones R
  Rear L	-	Analog and digital Rear output
  Rear R
  ADC Rec L	-	Audio to be sent back to Host CPU for recording
  ADC Rec R
  Mic Rec	-	More Audio to be sent back to CPU, mono 8KHz only
  out6r		-	unknown
  out7l		-	unknown
  out7r		-	unknown
  out8l		-	unknown
  Analog Center	-	Analog Center on SBLive-5.1
  Analog LFE	-	Analog LFE on SBLive-5.1
  out9r	to out15r	unknown


It's possible that some of those "unknowns" may in fact be inputs or outputs
on your system. If you discover a new I/O, please send a note of it to 
emu10k1-devel@lists.sourceforge.net


Routing
-------

To add a route, one uses emu-dspmgr with the -a option, for example:
	emu-dspmgr -a"Pcm1 L:Rear L"

to see a list of routes, the -r option can be used. To remove a route,
one specifies a route with the -r options, e.g.:

	emu-dspmgr -r"Pcm1 L:Rear L"

If you get an error "Cannot remove route", this may occur if a loaded patch
depends on needs that route to not be left dangling (more on patches in the next
section).


Patches
-------

Patches (i.e. 'effects') are loaded and unloaded using the emu-dspmgr tool. An
effect can be attached to any input or output. When loading an effect, you
must specify which group of inputs or outputs the patch will be attached to:

emu-dspmgr -l"Pcm L" -l"Pcm R" -f"/usr/local/share/emu10k1/flanger_2.bin"

This loads the stereo patch "flanger_2" onto the two Pcm inputs. Now any mp3, ogg or
wav played will have the flanger effect applied.
 

Control GPRs
------------

Effects need to have a controllable parameters. This is what the so-called "control
GPRs" accomplish.

To see list of available control GPRs use the -c option:

emu-dspmgr -c

You'll get a listing of all loaded effects and the control GPRs available to each.
For example, the tone control patch has the following output:

  Patch: Tone Control
    name: bass
    addr: 0x19
    mixer: bass_l
    value:  0x07ffffff (0000000000 - 0x7fffffff)

    name: treble
    addr: 0x1a
    mixer: treble_l
    value:  0x07ffffff (0000000000 - 0x7fffffff)

This means 2 controls are available, "bass" and "treble" (The controls name is after "name:" not "mixer:").
If you wanted to change the value of treble to 1/2 scale, you would do the following:

emu-dspmgr -p"Tone Control" -c"treble" -s#0.5

-p specifies the patch name, -c the control, -s is the value to set. You can
enter the set value with 3 prefix modifiers:

# - a fractional value (0x7fffffff is 1, 0x80000000 is -1)
& - delay in seconds (exponential format is ok, i.e.  &1e-3)
% - delay in number of samples


Control Sharing:

One interesting thing about Control GPRs is that the are shared amongst similar
effects. So if you have 2 tone controls effects loaded, the above example would
actually change both at the same time.

To get around sharing, you must rename the patches at load time. You can do
this using the -p options as follows:

emu-dspmgr -p"my_tone" -l"Pcm L" -f"/usr/local/share/emu10k1/tone.bin"



Volume Controls
---------------

Most people will notice that the driver now has a lot less volume controls. This
occurred because of the usage of the ac97_codec module in the kernel (re-use==good). 
The ac97_codec only provides volume controls on the analog sources (and pcm-to-front).
To fix this problem a method is used to map control GPRs to the oss mixer controls 
(e.g. aumix/gmix/kmix/etc).


To map a mixer element, we use the -m option as follows:

emu-dspmgr -p"my_tone" -c"bass" -m"line3_l"

For a complete list of mixer controls, use the -m option alone.

If a Control GPR is mapped to a mixer control, it'll have the mixer control
listed after "mixer:" when the controls are listed with the -c option.


INTERNAL MIXER
==============


One last thing which needs to be said, is that there are 2 mixers on the SBLive.
An analog mixer via the AC97 chip, and the dsp mixer via dsp code on the emu10k1.
This can lead to much confusion, the SBLive drivers on that other platform do a very 
good job at hiding this from the users, this is something which we could improve on. 


Graphically, the mixers looks like this ( '*' represent volume controls):


          emu10k1                                  AC97 chip
        ----------------                   ------------------------------------|
PCM    |               |  Analog_out      |                                    |
 ----->|               |----------------->|-----*-------<Sum>--------------*-->|------->Front out
(from  |               |                  |            //  | \      |          |
CPU)   |               |                  |          / |   |    \   |          | 
       |     DSP       |                  |         *  *   *    *   *(igain)   |
       |   Routing     |<---------------- |<--\     |  |   |    |   |          |
       |    Code       |  Analog_in       |    \---< Rec  select > -/          |
       |    and        |                  |         |  |   |    |              |
       |   patches     |                  |------------------------------------|
       |               |                            ^  ^   ^    ^
       |  (Via         |                            |  |   |    |
       |   emu-dspmgr) |---> Digital Front          |  |   |    |
       |               |                          CD Mic Line  Video
       |               | 
       |               | 
       |               |--> Analog & Digital Rear 
       |               | 
       |               |<--- Digital sources (CD, Spdif, any Live drive input (including analog sources)) 
       ----------------


Note that Analog_in is what ever you've selected as record source in your OSS mixer. If you select IGain
you'll get a copy of the Front_out (including analog_out, cd mic, line, video)


