Mar 1rst, 1996

Unofficial Advanced Gravis Ultrasound Drivers ("Manley Drivers")
Copyright 1994-1996 Robert J. Manley and Multi-Player Computer Adventures Inc.
Version 1.10 - SHAREWARE - please read the REGISTRATION section for details
Release 1 of the "next generation" OS/2 driver for the GUS

FEATURES

	- basic GUS rev 3.7 and MAX/daughtercard mixer support
	- 16-bit 44Khz stereo wavefile playback
	- native GUS MIDI playback with patch caching
	- multi-session (many registered streams - one active)
	- multiple (2) ACTIVE digital audio streams (only GUS and Mwave?)
		- this feature requires running MINSTALL to update MMPM2.INI
	- simultaneous DART/Digital Audio/MIDI/MOD (in shared mode = /S) (!)
	- Ultrasound specific OS/2 VDD giving DOS sessions:
	  - reduced interrupt latency
	  - hardware virtualization
	  - MIDI port emulation of Roland MPU-401 in UART mode
	    (allowing WinOS2 to load and use those drivers - hooray!)
	  - GM emulation for DOS and Windows sessions under OS/2 with
	    the goody pack which is only sent to registered users
	- absolute lowest system overhead possible
	- rigorous testing

	***** support for Sander van Leeuwen's
	      GUS native OS/2 MOD player, UltiMOD! *****


	Here is what it has been tested and known to work with:

	- OS/2 2.1 with MMOS2 CSD, OS/2 2.11 (with its MMOS2 CSD), Warp!
	- system sounds
	- digital audio applet
	- MIDI applet
	- compact disc applet and CD explorer (bug in version 2.3 hangs
	  PM message queue when using digital transfer)
	- bigben2
	- dmplayer 1.01
	- video player / Ultimotion
	- wave doctor
	- multimedia mahjongg
	- GUSmixer (even while the device is in use!)
	- play.cmd (thanks to TFS for reminding me about this one)
	- WinOS2 apps
	  - media player
	  - Cakewalk Pro
	  - Midisoft Recording studio


*** NEW INSTALLATION instructions

	- Uninstall Gravis' drivers if installed
		- MINSTALL with that package and select zero Ultrasounds

	- Uninstall Manley drivers if installed
		- confirm no "ULTRA" strings in CONFIG.SYS

	- MINSTALL this package
		- new ULTRADD switches:
			- /P:<GUS base>,<codec base>
			- /I:<GF1 IRQ>,<MIDI IRQ>
			- /D:<play DMA>,<rec DMA>
			- /C:<number of voices to use> (default = 28)
			- /J (enable joystick)
			- /L (always enable line-in)
			- /V (verbose messages at startup)
		- NOTE: v 1.10 requires an MINSTALL to enable multiple
		  ACTIVE digital audio (DART/WAVE/AVI) streams

	- Change drive/directory on ULTRADMN.EXE line in CONFIG.SYS to main
	  UltraSound directory if not <drive>:\ULTRASND

	- CONFIG.SYS should have lines similar to this:
		DEVICE=D:\MMOS2\ULTRADD.SYS /P:240,32C /I:12,5 /D:7 /J /V
		DEVICE=D:\MMOS2\ULTRAVDD.SYS
		RUN=D:\MMOS2\ULTRADMN.EXE C:\ULTRASND
		RUN=D:\MMOS2\ULTRALDR.EXE

	- shutdown and reboot

	- unzip utilities package
		- create program object for ULTRAMEM and place in startup folder
		- if having problems, run ULTRDIAG
			- if running an OS/2 app, select ignore at error box

	- other neat things to try:
		- override default patch sizes (8-bit with <= 512K) or load
		  custom patches with specific ULTRASND.INI file by specifying
		  after ULTRALDR either at boot or later
			- loading 16-bit patches is faster than 8-bit
		- kill ULTRADMN, re-run with critical priority, and then remap
		  instruments with ULTRALDR (with or without INI filename)
		  (this makes patch loading even faster but can seriously
		  degrade system performance)


*** LIMITATIONS ON "NEXT GENERATION" SHAREWARE VERSION

	- only 3 MIDI sessions per boot
	  (note that the MIDI applet need only be closed to use the
	   card under DOS/Win or with UltiMOD)
	- no GM "goody pack" for DOS/Win
	- no saving of UltiMOD INI file


*** REGISTERED USERS

	- if you haven't received a key from myself or Sander, please
	  e-mail me and we'll send you one.  Please make sure you use
	  the ultrareg.exe supplied with the driver.


HARDWARE EMULATIONS

In addition to virtualizing the Ultrasound I/O ports to DOS sessions, the
supplied OS/2 virtual device driver (VDD) ULTRAVDD.SYS also emulates the
following devices when selected in the AUDIO_ADAPTER_EMULATION DOS setting:

	- Roland MPU-401 MIDI interface in UART mode (e.g. Windows).
	  Select I/O address of 0x330 and IRQ of 2/9 (not used yet).
	  MIDI is re-routed through the GUS MIDI port to an external synth
	  (not played natively as in MegaEm).

**** NOTE: native DOS GM emulation is now done! (like MegaEm for OS/2)
**** Register this software and get the files required to enable this
**** functionality by e-mail or if neccessary, ground mail

Future directions are to add Sound Blaster and enhance Roland emulation.

Please note that neither SBOS or MegaEm should be run under an OS/2 DOS
box.  These programs require features of the 386 that cannot be granted
to a VDM under a protect mode OS without comprimising system integrity.

	UNDER NO CIRCUMSTANCES SHOULD SBOS or MEGAEM BE RUN!


WinOS2 CONFIGURATION

It is recommended that all WinOS2 users keep a separate copy of their
SYSTEM.INI and CONTROL.INI files for real Windows and WinOS2.  Doing this
will allow the Gravis supplied Windows drivers to work while under real
Windows and these drivers to provide MPU-401 emulation under WinOS2.  A
good system to use is to copy each of these files to another with the same
filename root but with the extension ".DOS" after a successful run of real
Windows.  Do the same with the extension ".OS2" after running this setup
without problems.  Before starting either system, copy the OS specific
versions over their proper files.  PLEASE BE CAREFUL with this and take
the time to understand what you are actually doing!

The first thing to do is get rid of all references to the Gravis drivers
in your Window's SYSTEM and CONTROL ini files (of course, this is only
after you've already made backup copies of these files for real Windows
as described above).

These are the lines in your real Windows SYSTEM.INI to comment out with a
';' character at the beginning to disable Gravis' drivers and avoid that
stupid error message listed in the QUESTIONS section below:

	device=grvsultr.386
	midi=ultrasnd.drv
	...
	midi1=ultmport.drv
	wave=ultrasnd.drv
	AUX=ultrasnd.drv
	mixer=ultrasnd.drv

These are the lines in your CONTROL.INI file to do the same with:

	ultmport.drv=UltraSound MIDI Port
	ultrasnd.drv=Ultra Wave and MIDI Synth
	...
	midi=ultrasnd.drv
	midi1=ultmport.drv
	wave=ultrasnd.drv
	AUX=ultrasnd.drv

The next thing to change are the parameters Windows uses for the system
timer which drives the MIDI playback.  Search for the following block in
your SYSTEM.INI:

	[timer.drv]
	TIMERMax386Res=10
	TIMERMax286Res=10

Change both values from 10 to 1.

Next fire up WinOS2 and install the Roland MPU-401 drivers through the
"Drivers" setup inside Control Panel.  Now go into the MIDI Mapper and
create a setup called "UltraVDD".  Select the Roland MPU-401 device as
the destination port for all MIDI channels and then click on "OK" to
complete the setup.

If you are running full OS/2 (with IBM's WinOS2), you may wish to copy
the TIMER.DRV from your real Windows SYSTEM directory to the equivalent
WinOS2 directory after renaming the original.  This driver seems to give
more accurate MIDI timing for Windows based MIDI sequencers.


KNOWN BUGS AND LIMITATIONS

 - MPU-401 interrupt driven recording isn't working yet (booo, hiss)
 - no text in Description field for AUDIO_ADAPTER_EMULATION property
   (this is a VDM limitation of OS/2 on Intel platform)
	- please remove SIO or ask Ray Gwinn to reduce the number he uses
 - the MMPM digital audio player truncates the last buffer on large audio
   files when the sampling rate is non-standard (11, 22, or 44 KHz)
	- use "play file=<filename>" to test

   New to next generation:
 - some instruments (especially wind) cause clicking

   New and SERIOUS:
 - high speed I/O bus (>11.1 MHz) can cause serious problems with
   with WAV and MIDI playback
	- I can't reproduce this problem but below are a couple of
	  suggestions.  Please let me know what happens.

	- lower the number of voices from the default of 28 down to 22 (or
	  even 14) with the /C:22 switch on the ultradd line in the config
	- run ultrinit in a DOS box before using the card in OS/2


MOST COMMONLY ASKED QUESTIONS

Q. Why do I get an error when starting the MIDI application?
A. If this is your fourth time running it since reboot and you haven't
   stamped the driver with your registration key, this is normal.  See
   the REGISTRATION section for more details.

Q. Why don't I hear anything when using WinOS2 MIDI applications?
A. If you are not a registered user and don't have a MIDI synth connected,
   you won't.
A. If you do have a MIDI synth, check the WinOS2 CONFIGURATION section above.
A. If you are a registered user, please read the WinOS2 CONFIGURATION section
   in this document and the INSTALLATION instructions included with your GM
   "goody pack".

Q. Why is there a delay before hearing a system sound?
A. OS/2 must swap out blocks of memory to give the MMOS2 subsystem the
   storage that it needs for holding the sound sample.  When enough memory
   is already free (such as immediately after a system sound), the delay
   should be almost unnoticeable.

Q. Why do I get the error message "The Ultrasound driver requires enhanced
   mode to run" when trying to start a full-screen WinOS2 session?
A. Gravis' drivers include a Windows Virtual Device Driver (VxD != OS/2 VDD)
   which cannot be loaded by OS/2 for system integrity reasons.  When the
   load fails, WinOS2 (and Windows) interpret this error as the system not
   running in 386 enhanced mode since that is the mode required for loading
   and using VxDs.

Q. Why do my seamless WinOS2 sessions just sit there and never start?
A. See Q and A above.  When the VxD load fails, WinOS2 can't continue nor
   can it properly exit.  Use a session killer like Watchcat to kill it.

Q. Why doesn't SBOS or MegaEm work?
A. Please read the HARDWARE EMULATIONS section.


LEGALESE

This software is provided AS IS.  No warranty of any kind, expressed or
implied, is granted including any warranties of quality or fitness for
a particular purpose.  Under no circumstances will either Robert J. Manley
or Multi-Player Computer Adventures be held responsible for any damage
that results directly or indirectly from the use of this product.


REGISTRATION

*** NEW as of 1.10 - Registrations are now also taken by BMT Micro which
does accept credit cards (yeah!).  Please see the file BMTORDER.DOC for
details.  If you instead wish to register directly with MPCA ...

Please fill in the following information and send it along with a cheque
or money order for $25.00 US or an equivalent amount in your currency to:

	Multi-Player Computer Adventures Inc.
	14845-6 Yonge Street, Box 314
	Aurora, Ontario, Canada
	L4G 6H8

   Name: __________________________________________________

Company: __________________________________________________

Address: __________________________________________________

       : __________________________________________________

       : __________________________________________________

 e-mail: __________________________________________________

  phone: __________________________________________________

Price includes 7% GST for Canadians and 8% PST for residents of Ontario.
Some future versions of this product may only be distributed commercially
but will be sent free to all registered users if deliverable by e-mail.

*** NEW as of version 0.8a ***
Even hotter :): Sander and I have agreed to combine the registration process
for this driver and UltiMOD - $25 US now gets you registered status for both
products!  Users in North America should register with Multi-Player at the
address given above while those in Europe and other locations should send the
check to Sander at the address given in ULTIMOD.DOC.  Previously registered
users of either product will now also be granted that status for both products
as well.


BUG REPORTS

*** NEW e-mail address ***

Please send all bug reports, gratuitous worship, whatever, to me through
e-mail at: rjm@io.org.  I enjoy hearing from all users.

       Driver version: 1.10

      Problem symptom: _____________________________________________

    Fix or workaround: _____________________________________________

         OS/2 version: ______

GUS hardware revision: ___

  Daughtercard? (y/n): _

 External MIDI? (y/n): _

           GUS memory: ____ K

        System memory: __ M



WHAT'S NEXT

 - resource manager support
 - recording
 - generic MMPM mixer support
 - RTMIDI
 - ship release 2

 - new VDD/Win drivers which use and share(!) the card with the PDD
	- simultaneous Win and OS/2 audio applications
 - SB emulation
 - DONE!


Thanks to:

	Sander, of course
	John Smith and David Bollo at Gravis
	Brent Davis and Linden deCarmo at IBM