########################
AUDIOSCIENCE ALSA DRIVER
########################

.. WARNING::
  THIS IS A BETA DRIVER, USE AT YOUR OWN RISK
  Send feedback to <support@audioscience.com>
  This software is distributed under the GPL - see asihpi.c

See also http://alsa-project.org/main/index.php/Matrix:Module-asihpi

.. contents::

SUPPORTED CARDS
===============
This applicable to ASI 5xxx, 6xxx, 87xx and 89xx cards.
(See also LIMITATIONs section)

BUILD AND INSTALL
=================
To build and install using current kernel ALSA headers
   run make && make install in this directory
   
.. NOTE::   
   This just build a compatible snd-asihpi module.
   By default a module built this way will be installed in $kerneldir/extra,
   the original from-alsa-source or in-kernel module will still be in $kerneldir/sound/pci/asihpi
   To use the orignal again, delete snd-asihpi.ko in extra, and run depmod.

To build using alsa source tarballs
   See script build-asihpi-alsa

To build using alsa git repositories
   Contact AudioScience

CARD INDICES
============
snd-asihpi will try to allocate the ALSA card index equal to the ASI card index set by the jumpers on the card.
However, if you have another sound card installed, and its driver is loaded first, it may already have been assigned the same index (usually zero).
In this case the ASI card will get the next available ALSA index.

You may be able to add "options snd-<othercard> index=2" to your modules.conf
to free up the desired indices for your ASI cards.

ASI streams map to ALSA subdevices. Device is always zero.
  ``$ aplay -Dhw:0,0,2 sound.wav # Play on Card 0, Device 0, Stream/subdevice 2``


CONTROLS
========
To list them all
    ``$ amixer controls``

Control Naming
--------------
Controls are named according to ALSA conventions where possible.

The general format for an ALSA control name is "SOURCE SINK DIRECTION TYPE". Some examples

"PCM 0 Playback Volume"
    master volume of player 0
"PCM 0 Playback Switch"
    master mute of player 0
"PCM 0 Line 0 Playback Volume" 
    matrix volume between player 0 and output 0
"Line 0 Line 0 Monitor Playback Volume"
    feedthrough volume from input 0 to output 0
"PCM 0 Capture Route"
    select one source for recorder 0 (more common)
"Line 0 PCM 0 Capture Volume"
    matrix volume between input 0 and recorder 0 (less common alternative to capture route) 

Volume
------
The units of volume controls are milliBels. (1/100 of a dB)

Typically volume controls range from -19200 or -10000 to 0

To set a volume control to -10dB (you need the "--" when using -ve parameter values)
    ``$ amixer cset numid=5 -- -1000 -1000``

Level
-----
The units of level controls are dBu.

Level controls range from about -10dBu to (+20dBu up to +26dBu)

Note that level controls are not direct gain controls. The level control
sets the absolute input or output level that corresponds to full scale
digital sinewave.

In particular, increasing input level setting effectively *decreases*
input gain.

PROC FILE
=========
``/proc/asound/card0/info``  contains some info about the card
There will also  be a symbolic link to the card directory eg ``/proc/asound/ASI6244``

LIMITATIONS
===========
Only PCM is currently supported.

Meter controls are partially supported.
HPI meters return a value in milliBels, however this requires a floating point
operation on the host, not feasible in a kernel driver.
Therefore the ALSA driver returns a roughly linear meter value
where 0x7FFFFFFF is fullscale (0dB)

Other controls (aesebu, compander, parametric equalizer, vox, bitstream, microphone)
are currently unsupported. Volume autofade is not supported.

CHANGES
=======
2012-05-01
    Convert to reStructured Text.
    Add control name examples.
2008-05-30
    Add current kernel build instructions.
2008-02-27
    Control naming now has all indices in name, doesnt use control index.
    Update list of supported cards.
    Update meter description.
