
    MSND - a Un*x/Linux AD/DA-driver for MultiSound/Tahiti/Monterey
    ===============================================================

    MultiSound(classic)/Tahiti/Monterey are soundcards made by Turtle
    Beach Systems. They can, among other features, record and play digital
    audio at rates up to 44.1kHz stereo on their onboard AD/DA-converters.

    This device driver accesses the converters of a single card, allowing
    high quality harddisk recording/playback without dropouts - even on a
    busy system! Unfortunately the other features as wave synthesis, MIDI
    and signalprocessor (DSP) CANNOT be used. Also, recording and playback
    at the same time is not possible.

    The driver was originally designed to run on a generic System V386/
    R3.2. It now includes an EXPERIMENTAL interface to Linux, providing
    the same functionality. This interface doesn't yet coexist with
    VoxWare, the default soundcard driver on Linux. It was checked to
    operate on several kernel versions between 1.0.9 and 1.2.1.


    Contents:
    ---------

	1. Features
	2. How to obtain necessary DSP-code images
	3. Installation
	4. What's new in this release?
	5. Concept of operation
    	6. Reliability, support, improvements
	7. Credits
	8. Author and where to get more information
	9. Copyright and disclaimer


    1. Features
    -----------

	* interfacing soundcards made by Turtle Beach Systems, Inc.,
	  that are using proprietary Harry Cane (or so ...) arcitecture;
	  tested with MultiSound(classic)/Tahiti/Monterey

	* recording or playback directly at 11.025, 22.05 and 44.1kHz,
	  mono or stereo, with big- or littleendian 16bit samples (refer to
	  Lance Norskog's package `(L)sox' for conversion of other formats)
	  BUT: NO MIDI, NO ADVANCED DSP-PROGRAMMING, NO SIMULTANIOUS
	  REC/PLAY, NO PROTHEUS/WAVE-SYNTHESIS, NO SPECIAL EFFECTS

	* flexible interrrupt buffering scheme for robust continuous
	  recording and playback from/to disk; can keep up with sync
	  even on a busy system

	* driver kernel interfaces and driver installation interfaces to
	  a) ATT Unix V386/R3.2 (might run as is with other systems
	     like Interactive and SCO, but NOT tested)
	  b) Linux, replacing VoxWare, thereby loosing VoxWares
	     functional benefits (like /dev/audio) 

	* uses a single character device which can be read or written;
	  parameters like rate and format of are controlled by ioctl()

	* implements control of `IN' and `AUX' sensitivity 

	* three application programs for playback (featuring continous
	  repeat of any file without delaying samples when rewinding),
	  recording (set number of samples to be recorded) and control
	  are supplied

	* for copyright reasons the necessary DSP56001-code images have
	  been excluded from the source tree; they have to be obtained
	  from a public source (see below)


    2. How to obtain the necessary DSP-code images
    ----------------------------------------------

	Use the World-Wide-Web to retrieve the MultiSound software package
	multi_10.zip from <http://www.cs.colorado.edu/~mccreary/tbeach
	(it has to be the old Version, NOT multi_11.zip, NOT multi_20.zip).
	Extract the files msndpp11.bin, msndpr11.bin and mdiag.bin
	from the archive and place them in this directory.


    3. Installation
    ---------------

	See file INSTALL.


    4. What's new in this release?
    ------------------------------

	Release 2.0 was first public release	
	Current release:

		* Linux-Interface
		* stops gracefully if disk/filesytem doesn't
		  get/send data in time (overrun condition)

	Details see file HISTORY.


    5. Concept of operation
    -----------------------

	The driver is implemented as a character device /dev/msnd. If the
	device is read after opening, recording will be initiated.
	Similaryly if the device is written, playback will be initiated.
	The operational parameters of recording or playing (e.g. sampling
	rate or record/playback-limits) can be set by ioctl-calls immediately
	after open. These settings will be kept after closing the device
	until another ioctl is successfully performed.

	If for example the default settings after booting the systems are
	44.1kHz and stereo, a shell command like

		cat </dev/msnd	>foo

	would record audio data to the file foo until the process is killed
	or a selectable limit of samples is reached. After that one could use
	command

		cat foo >/dev/msnd

	to play the file back again. In order to set a different sampling
	rate a process would have to perform ioctl-calls on the /dev/msnd.
	For convenience the commands msndctl, play and rec are provided.
	The first allows to alter the operational paramters, whereas the
	other two also directly record to or, respectively, play from a file.


    6. Realiability, support, improvements
    --------------------------------------

	The driver has been used for a long time time on a generic Unix
	V386/R3.2 using the MultiSound classic. A Tahiti has been tested
	for a day. The Linux interface is EXPERIMENTAL. It just encapsulates
	the code of the V386/R3.2 driver. Using the MultiSound classic it
	has been tested for a short time on Linux 1.0.9, 1.1.88, 1.2.1.
	Compiler was gcc 2.5.8. Greg Smith <greg@gms.org> has tested
	msnd-2.1 under Linux 1.1.45 using a Monterey. See also HISTORY-file.

	If you experience substantial problems please contact me. Maybe I
	can help. If all goes well drop me a note too! Whereas I will
	rather confine myself to bugfixing Greg is also plannig improved
	releases. For suggestions on improvement see file TODO. Eventually
	this driver should merge into VoxWare, if Hannu Savolainen
	<hannu@voxware.pp.fi> finds the time.

	Don't get too excited about functional improvements: TBS has kept a
	strict information policy in the past. It seems unlikely that they
	will ever release any information how to program the hardware. All
	information that was needed to implement the present functionality
	of this driver was obtained by painfully debugging of the DOS
	executables.


    7. Credits
    ----------

	Thanks to

	* Greg Smith <greg@gms.org> for discussions, suggestions and
	  testing of the experimental Linux interface.
	* Hannu Savolainen <hannu@voxware.pp.fi> for help with the
	  experimental Linux.
	* Eddie from Music Shop, Munich, for generously allowing me
	  to test the MultiSound and Tahiti before buying.
	* Sean McCreary <mccreary@cs.colorado.edu> for maintaining the
	  WWW archive site and the mailing list (see below), without it
	  I never would have felt encouraged to publish this driver.


    8. Author and more information
    ------------------------------

	Questions, remarks, suggestions and advice are welcome
	
			Markus Mummert
	* SNAILMAIL:	Emanuelstr. 27
	  		D-80796 Muenchen
	  		Germany
	* PHONE:	+49 89 300 44 70
	* MAIL:		<mum@mmk.e-technik.tu-muenchen.de>
	  		Please Note: this adress is checked depending
			on traffic - maybe only twice a month at the worst
			My own system is offline.

	For further information check 

	* WWW:		<http://www.cs.colorado.edu/~mccreary/tbeach>
			Archive site, FAQs on turtle beach soundcards
	* MAILING LIST:	read all about it on WWW-page
	* USENET:	<comp.sys.ibm.pc.soundcard>


    9. Copyright and disclaimer
    ---------------------------

	Copyright (c) 1994-1995 by Markus Mummert

	Redistribution and use of this software, modifcation and inclusion
	into other forms of software are permitted provided that the following
	conditions are met:

	1. Redistributions of this software must retain the above copyright
	   notice, this list of conditions and the following disclaimer.
	2. If this software is redistributed in a modified condition
	   it must reveal clearly that it has been modified.
	
	THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
	AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
	TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
	PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR
	CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
	EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
	PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
	PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
	OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
	USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
	DAMAGE.


    ===EOT===$Id: README,v 2.1.0.1 1995/04/11 14:46:40 mummert Exp mummert $

