Release notes for the ICEnsemble Envy24 (ICE1712) driver
========================================================

Note! The Envy24 driver is a separately priced option of OSS. You need to
select the ENVY24 option when ordering the permanent OSS license
(the demo license contains this option).

OSS 3.9.6e version includes BETA drivers for some new M Audio cards
(410, TDIF and 1010LT). They have not been fully tested yet. Also
support for Terratec EWS88D is improved from earlier OSS versions and
the ADAT interface is now supported (BETA). Support for Terratec
DMX6Fire is under progress. The driver recognizes the card but only the
MIDI port works.

The following cards are currently supported:

M Audio (www.midiman.com):

- Delta 1010
(World clock sync is not supported)
- Delta 44
- Delta 66
- Delta DIO 2496
- Audiophile 2496
- Delta 410 (BETA)
- Delta TDIF (BETA)
(See notes for Delta TDIF below)
- Delta 1010LT (BETA)

Terratec (www.terratec.com):
- EWS88MT
- EWS88D (BETA) (See notes for EWS88D below)
- EWX24/96
- DMX6fire 24/96 (BETA) (Many features not supported yet. In particular there
is no S/PDIF (digital) input/output).

ST Audio (www.staudio.com):
At this moment only analog output is supported with ST Audio cards.
- DSP24
- DSP24 Value

There are known problems with few applications:
- With RealEncoder/RealProducer you need to turn on few options in the
options.cfg (see below).
- With mpg123 (at least versions 0.59r and earlier) you need to modify the
sources and remove the call to ioctl(SNDCTL_DSP_GETBLKSIZE). Use fixed
buffer size (say 512 or 1024) instead. This hopefully gets fixed in
later versions of mpg123.

Notes for M Audio Delta TDIF
----------------------------

The Delta TDIF driver is still a beta test version which means that
there are some known problems.

Loading OSS for the first time after boot takes really long and the
system will stop responding for about 5 seconds. This is normal and is
caused by loading of the board firmwarare.

You may get some "Envy24: Unrecognized S/PDIF chip ID NN" messages during
soundon. These are related with earlier attempts to use external sync.
If they occur you should shut down and power off the system and restart it.

There are some problems with the external world clock sync mode and it usually
just doesn't work. Internal and S/PDIF sync modes work better. Use internal
sync if possible since it's most reliable.

The analog codec is not supported yet.

Notes for EWS88D
----------------

The EWS88D driver is a beta test version. It works but all of the features
have not been fully tested yet.

There are few EWS88D specific settings in ossmix/ossxmix.

- ews88d.spdin (currently COAX)
Selects the SPDIF input source between optical and coax.
- ews88d.optout (currently SPDIF)
Changes the mode of the optical output between ADAT and SPDIF.
- ews88d.adatloop ON|OFF (currently OFF)
Enables looping of ADAT input straight to the ADAT output in hardware level.

The above settings have dependencies between each other so many of the
possible combinations just don't work.

The WCLOCK sync mode (envy24.sync=WCLOCK) means actually ADAT sync. The
ADAT input signal is used as the clock source.

Installing the driver
---------------------

The card will be automatically detected and configured by oss-install/soundconf
and there are no adjustable options in soundconf. However there is one
parameter that can be defined in the options.cfg file (in the directory where
oss was installed).

By default OSS creates separate device files for each input and output stereo
pair supported by the device. So after executing soundon the /dev/sndstat file
should look like:

OSS/Linux 3.9.3i (C) 4Front Technologies 1996-2000

License serial number: XXXXXXXXX
Options: ENVY24
This license is for Internal use by 4Front Technologies.

Build: 2.3.45

Card config:
IC Ensemble ENVY24

Audio devices:
0: M Audio Delta 1010 out1/2
1: M Audio Delta 1010 out3/4
2: M Audio Delta 1010 out5/6
3: M Audio Delta 1010 out7/8
4: M Audio Delta 1010 S/PDIF out
5: M Audio Delta 1010 in1/2
6: M Audio Delta 1010 in3/4
7: M Audio Delta 1010 in5/6
8: M Audio Delta 1010 in7/8
9: M Audio Delta 1010 S/PDIF in
10: M Audio Delta 1010 input from mon. mixer
11: M Audio Delta 1010 (all outputs)
12: M Audio Delta 1010 (all inputs)

Synth devices:

Midi devices:
0: M Audio Delta 1010

Timers:
0: System clock

Mixers:
0: M Audio Delta 1010

Note! The actual /dev/dsp# numbers may be different on your system. Check the
right ones by looking at the output procuced by "cat /dev/sndstat"
command.

With the above configuration you can use /dev/dsp0 to /dev/dsp4 for playback of
stereo streams (if you play mono files the signal will be output only from
the left channel). /dev/dsp0 to /dev/dsp3 are connected to the analog outputs
while /dev/dsp4 is the S/PDIF output.

The /dev/dsp5 to /dev/dsp10 device files can be used for
recording). /dev/dsp5 to /dev/dsp8 are the analog inputs.

/dev/dsp11 and /dev/dsp12 are "raw" input/output device files. They will be
described in detail in the "Raw I/O devices" section below.

It's also possible to make OSS to create individual device files for every
channel (this creates twice as many device files than the default setting). To
do this just append envy24_skipdevs=1 to the options.cfg file. This is usefull
(only) if you are working on mono rather than stereo signals. However please
note that setting envy24_skipdevs=1 does _NOT_ lock the device files to one
channel mode (the application can still set them to stereo or multi channel
mode if it likes).

It is possible to set all device files to mono only mode by setting
envy24_skipdevs=1 and envy24_force_mono=1. However this mode disables
stereo and multi channel usage for all devices so in general it should not
be used.

By default the driver will create output devices before the input ones. By
setting envy24_swapdevs=1 in options.cfg you can ask OSS to create the device
files in opposite order (input device files before the output ones). This may
be usefull when using RealProducer.

As a workaround to a bug in RealProducer you also need to create some dummy
mixer devices by defining envy24_realencoder_hack=1 in options.cfg. Without
these extra mixer devices RealProducer will not be able to access other than
the first input device.

Problems with too many audio devices
------------------------------------

By default OSS creates a large number of device files for each envy24 card.
This may be a problem when multiple cards need to be used in the same system.
Adding the envy24_devmask option to /usr/lib/oss/etc/options.cfg should
help in most cases because it removes the devices that are actually not
needed in the systenm.

The envy24_devmask number is the SUM of the following values:
1 - Create primary (analog/ADAT/TDIF) outputs
2 - Create primary (analog/ADAT/TDIF) inputs
4 - Create S/PDIF outputs
8 - Create S/PDIF inputs
16 - Create monitor input device
32 - Create the "raw" input and output devices.

For example envy24_devmask=12 (4+8) creates only the S/PDIF devices.
To enable all possible (current or future) device files set envy24_devmask
to 65535 (default).

Using the driver
----------------

If possible make your application to open the right device file (/dev/dsp0 to
/dev/dsp10) explicitly. It's also possible to use the default devicefile
(/dev/dsp) since OSS now supports automatic device allocation (it opens the
first available input or output devicefile depending on the open mode).

The channel allocation mechanism between device files is very flexible. Even
there is a device file for every stereo pair (or a mono channel) it's possible
to use any of the device file to access multiple channels. For example an
application can open /dev/dsp0 and set the number of channels to 10. In this
way the application can play all 10 channels (or any number between 1 and 10)
simultaneously (the samples will be interleaved).

There is simple automatic syncstart feature when using multiple applications at
the same time. Playback will not start before all currently open devices files
have started the playback operation. The same mechanism works for recording
(recording and playback operations are fully independent).

The Envy24 driver supports 8, 16 and 24/32 bit sample formats.

Selecting the sampling rate
---------------------------

Envy24 based cards are multi channel devices and all the channels share the same sampling
rate. For this reason the sampling rate is normally locked to the value selected using
ossmix. However OSS supports some other methods for changing the sampling rate.
There are four ways to change the sampling rate.

A) Basic method

Since all input and output channels of Envy24 work at the same sampling rate
it's not possible for the applications to select the rate themselves. Instead
the sampling rate is always locked to the currently selected rate. This rate
selection can be changed using the ossmix program shipped with OSS.

For example:

ossmix envy24.rate 48000

sets the sampling rate to 48000 Hz (default). The possible alternatives are:
8000, 9600, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000,
88200 and96000. When using S/PDIF inputs/outputs only the sampling rates 32000,
44100, 48000, 88200 or 96000 should be used.

B) External sync

It's possible to lock the sampling rate to the S/PDIF or world clock inputs
by setting the envy24.sync setting in ossmix to SPDIF or WCLOCK. However
the envy24.rate setting should be set manually to match the rate being used
(there is no autodetection for that).

C) Nonlocked method

It's also possible to turn the envy24.ratelock setting to OFF using ossmix.
After that the first application that opens the device can change the sampling
rate. However great care should be taken that this application gets the
recording/playback process fully started before any of the other
applications open their devices. Otherwise all devices will be locked to 8Khz.
Also keep in mind that subsequent applications will be forced to use the
sampling rate set by the first one.

D) Software SRC (sample rate conversion)

OSS now contains a very high quality software based sample rate converter.
It can be enabled by setting envy24.src to ON using ossmix (this feature
requires the MIX option in the OSS license).
After that OSS can do on-fly sample rate conversions between the actual
"hardware" sampling rate and the sampling rates used by the applications. In
this way every application may use different sampling rate. However there are
some drawbacks in this method:
- The hardware rate needs to be 44100, 48000 or 96000 Hz.
- The software SRC algorithm consumes some CPU time (1% to 20% per audio
channel depending on the CPU speed and sampling rates). For this reason this
method may be useless in multi channel use with anything else but the
fastest high end CPUs.
- Only mono and stereo (1 or 2 channel) streams are supported.
- The SRC algorithm does cause minor artifacts to the sound (SNR is around 60
dB).

Raw I/O devices
---------------

Support for raw I/O device files is a new feature included in OSS 2.9.5g or
later. These device files provide an alternative way to access Envy24 based
devices. With these devices it's possible to bypass the dual buffering
required by the "normal" input/output device files described above. This means
that also the mmap() feature is available and that the latencies caused by
dual buffering are gone. So these device files work much like "ordinary"
soundcards. However due to multi channel professional nature of the Envy24
chip there are some very fundamental differences. This means that these
device files can only be used with applications that are aware of them.

The differences from normal audio device files are:

1) The sample format will always be 32 bit msb aligned (AFMT_S32_LE). Trying
to use any other sample format will cause unexpected results.
2) Number of channels is fixed and cannot be changed. The output device
has always 10 channels (0 to 7 are analog outputs and 8 to 9 are the
digital outputs). This assignment will be used even with cards that don't
support digital (or analog) outputs at all. If the actual hardware being
used hass less channels the unused ones will be discarded (however they will
be fed to the on board monitor mixer).
The input device is fixed to 12 channels. Channels 0 to 7 are analog inputs.
Channels 8 to 9 are digital inputs. Channels 10 and 11 are for the result
signal from the on board monitor mixer.

Digital monitor mixer
---------------------

All Envy24 based cards have a built in monitor mixer. It can be used to mix all input
and output signals together. The result can be recorded from the "input from mon. mixer"
device (device 10 in the /dev/sndstat example above).

The monitor mix signal can also be routed to any of the outputs (including S/PDIF and
the "consumer" AC97 output of Terratec EWS88MT/D and any other card that supports it).

The settings in the gain.* group of ossmix are used to change the levels of all
inputs and outputs in the digital monitor mixer. The possible values are
between 0 (minimum) and 144 (maximum).

OSS permits using all 10 possible output channels of the monitor mixer even
with cards that have less physical outputs. These "virtual" outputs are only
sent to the monitor mixer and their signal is only present in the monitor
mixer output. To enable these "virtual" channels set the envy24_virtualout
parameter to 1 in options.cfg. This option has no effect with Delta1010, EWS88MT and
other cards that have 10 "real" outputs.

Selecting the sync source
-------------------------

On cards with S/PDIF and/or World Clock inputs it's possible to select the
sync source using

ossmix envy24.sync

The possible choices are:

INTERNAL Use the internal sampling rate as defined by envy24.rate
SPDIF Use the S/PDIF input as the clock source. The envy24.rate
setting must be set manually to match the actual input
sampling rate.
WCLOCK Like SPDIF but uses the world clock input signal
(Delta 1010 only).

Changing the input and output gains
-----------------------------------

OSS permits changing the input and output gains for the analog ports on certain
cards. Exact details depend on the soundcard being used. Use the ossmix command
to show a list of the known controls and look at the gain.* settings.

With some devices it's possible to change the gain controllers to be
continuous sliders instead of just enumerated ones. This can be done by
defining envy24_gain_sliders=1 in options.cfg.

Output routings
---------------

Output routing of output ports can be changed by changing the route.* settings
using ossmix. The possible choices are:

DMA - Playback from the associated /dev/dsp# device.

MONITOR - Output of the digital mixer (ounly out1/2 and S/PDIF.

IN1/2 to IN9/10 or
IN1 to IN10 - Loopback from the analog inputs

SPDIFL or
SPDIFR or
SPDIF - Loopback from the S/PDIF input.

Peak meters
-----------

Envy24 based cards have peak meters for the input and output ports of the
digital monitor mixer. ossmix can show these values under the peak.* group
(these settings are read only). The values are between 0 (minimum) and 255
(maximum). At this moment the only applications that supports these peak meters are
ossmix and ossxmix (a GTK+ based application that is available from 4Front Technologies).

About IDE disks/CD-drives and dropouts
--------------------------------------

IDE disk and CD-ROM drives may cause some interrupt latency problems which
may cause dropouts in recording/playback with Envy24 based cards.

When using the Envy24 driver together with IDE disks or CD-ROMs under Linux
it's highly recommended to enable 32 bit I/O mode and/or DMA. This can be done
with the hdparms command:

hdparm -d1 -c1 /dev/hd[abcd]

In some cases above is not enough. You may try some additional options. However
make sure you understand what you do.

hdparm -m16 -u1 -c3 -d1 /dev/hd[abcd]

This increases the system performance significantly.

Another method to solve the dropout problems is making the fragment size used
by the driver longer. This can be done by adding envy24_nfrags=N to the
options.cfg file. By default N is 16. Values 2, 4 or 8 make the fragments
longer which should cure the dropout problems. However this may cause
latency problems with some applications. Values 32 and 64 decrease the
latencies but may cause dropouts with IDE.

Third method that helps in dropout problems is installing Andrew Morton's
low latency patches for Linux (2.4.x kernels). They are available from:

http://www.zip.com.au/~akpm/linux/schedlat.html