

			G U S   d r i v e r
		      -=====================-


This is new driver for Gravis UltraSound card. It's only in kernel 
module version. I'm writting this driver for one reason - I want
use all features of my GUS cards. OSS driver is pretty, but development
of universal sound driver for all soundcards eat very much time and
author can't quickly implement new things. So - if you want standard
- use OSS driver and if you want more fun with your GUS card - use this
driver.

This driver can be used for noncommercial purposes without restrictions.
If you want use this driver for creating of some sort commercial
sound or music, please, contact the author! For other restrictions
see to file POLICY.

					Happy GUSing !!!
 
					Jaroslav Kysela
					
For snail and other info look to SPONSORS file in top level directory...


Driver has already implemented following things:

	- support for up to 8 Gravis UltraSound cards
		- Gravis UltraSound Classic
		- Gravis UltraSound 16-bit Daughter Board
		- Gravis UltraSound MAX
		- Gravis UltraSound ACE
		- Gravis UltraSound Plug & Play
		- all other cards with InterWave (tm) chip
	- inteligent memory manager for onboard DRAM
		- dynamically allocated instruments
		- unlimited number of instruments
	- native synth interface (original idea & implementation)
		- direct control of GF1 registers
		- automatic volume ramp feature (ultraclick elimination)
		- automatic smooth pan feature (ultraclick elimination)
		- voice commands
		- channel commmands
		- instruments supported:
		  - simple (for MOD players)
		  - GF1 patch (.pat files)
		  - InterWave FFFF
	- full MIDI emulation (original idea & implementation)
        - emulation of USS/OSS 3.XX SEQUENCER
		- level 1 - /dev/sequencer
		- level 2 - /dev/music
		- MIDI emulation
	- PCM compatible with USS/OSS 3.XX
		- full DUPLEX support (doesn't work for DB-16 board)
		- full GF1 chip support
		- full CODEC chip support
                - full mmap() support for both (GF1 & CODEC) chips
	- MIXER	compatible with USS/OSS 3.XX with some extensions
		- full ICS chip support
		- full CODEC chip support
		- full InterWave chip support

Driver is now good stable and have been created in Linux version 2.0.X/2.1.X.
Computer 1)	Distribution - RedHat 4.0 (Colgate)
		CPU - Cyrix 6x86/120, 32MB RAM, PnP BIOS,
		BusLogic FlashPoint LW SCSI (Ultra-Wide) [PCI]
		Gravis UltraSound Plug & Play Pro card with 8.5MB DRAM onboard
		Gravis UltraSound Classic (rev 3.7) with 1MB DRAM onboard
Computer 2)	Distribution - RedHat 4.0 (Colgate)
		CPU - Cyrix 5x86/100, 32MB RAM, PnP BIOS,
		AdvanSys ABP940 SCSI [PCI]
		Gravis UltraSound MAX card with 1MB DRAM onboard
Synthesizer)	Roland XP-10

Driver is able to drive up to 8 cards although GUS supports only 7 IRQ and
5 DMA channels. Currently NONE of these resources can be shared due to ISA
bus limitations. Maximal number of installed GUS cards in your system can
be 5 at this time.

Configuration parameters in configuration file (gus.conf):

  Variable		Description
  --------------------------------------------------------------------------
  card			card number (1-8)
  id                    card id (used for /dev/gusinfo interface)
  logical		logical card number (1-8) - for order of cards
  port		 	port of GUS card - default = 0 (autosearch)
  irq		 	GF1 (and maybe CODEC) IRQ number for GUS card
			0 = autoconfiguration
  dma1			first DMA channel (GF1 download and CODEC record)
			0 = autoconfiguration
  dma1_size		size of buffer for first DMA channel
  dma2		 	second DMA channel (GF1 record and CODEC playback);
			0 = autoconfiguration
			gus_dma1 and gus_dma2 maybe equal if you don't plan
                        use full duplex PCM
  dma2_size		size of buffer for second DMA channel
  daughter_port		port of GUS 16-bit Daughter Board - 0 = disabled!!!
  daughter_irq		DB16 IRQ number
  daughter_dma		DB16 DMA number
  daughter_dma_size	DB16 DMA size
			0 = autoconfiguration


  Full duplex:
  ------------

    - >>> GUS Plug & Play - works - 100% <<<
    - GUS MAX - works
	- format and frequency of playback/record channels can't be different
    - standard GUS - works
	- recording can't be 16-bit
    - 16-bit Daugter Board
	- doesn't work due to one DMA channel limitation

  Notes:
  ------

    - mmap() for GF1 PCM is working, but don't burn your CPU with
      big playback rate... quake seems working...


Notes:
======

  - if make command reports error on line with 'insmod' command - try to
    look in file /var/adm/messages what's happened..
  - more information about driver is available by typing 'cat /dev/gusinfo'
  - /dev/dsp1 device is the same as /dev/dsp device, but it's set to
    8-bit as default
  - early GUS cards v3.7 which have some mixer channels flipped are detected 
    as GUS v3.5
  - if you want play huge files with maximum quality (44.1Khz, 16-bit, 
    stereo) - try to setup dma buffer size to 64KB

USS PCM compatibility:
======================

  - cthugha v0.8
  - Doom v1.8
  - Quake 1.01
  - Real Audio 2.0
  - and many others not listed here...

OSS (lite) sequencer emulator:
==============================

  Device mapping:

    - level 1 = /dev/sequencer
    - level 2 = /dev/music
    - device #0 - level 1 & 2 - MIDI UART INPUT / OUTPUT
    - device #1 - level 1 - OSS Gravis UltraSound interface (mod, gmod, playmidi -g)
    - device #2 - level 1 & 2 - GF1 MIDI emulation (playmidi -D 2 -e)
    - driver supports all GUS cards installed in your system
      - devices #3 - #5 - card #2
      - devices #6 - #8 - card #3 ... etc...                                                                                              = device #0

  Compatibility:

    - gmod 2.0.2, gmod 2.1, gmod 3.0.3
    - mod v0.8/v0.81
    - playmidi 2.2/2.3
    - xdrum 1.3
    - jazz v2.6b

To do:
======

  - ultraclick elimination 
  - MIDI instrument caching
  - implementation of the messages between multiple mixers
  - some next ideas are welcome

Revision history:
=================

v2.60a

  - effect support added for InterWave chip
  - InterWave LFO emulation added for GF1 chip and
    InterWave chip without onboard DRAM
  - OSS sequencer is now compatible with gmod+x-3.0.3
  - added support for all known MIDI commands to input queue and MIDI emulation
  - look to toplevel CHANGELOG for more details
 
v2.50a

  - 22. 1.1997
  - support for 2.1.X kernels added to driver and insgus
  - memory allocation manager
    - allow allocate/free blocks and instruments from onboard RAM memory
  - synthesizer code totaly rearranged
    - InterWave instrument support added (for both InterWave and GF1 chip)
  - daemon totaly recoded
    - bison + flex
    - InterWave FFFF support (for both ROM and FILE)
  - better USS sequencer emulation
    - now is emulated both level 1 and level 2
  - some little changes in CODEC routines
    - playback underruns (buffer looping) fixed
    - bug with SND_SETFMT ioctl and AFMT_S16_LE argument fixed
  - GF1 PCM routines totaly recoded for MULTITRACK PCM (1-32) support
    - note: multitrack feature isn't used yet.. it's prepared for future..
  - added -r options to insgus (restart of instrument daemons)
  - MMAP PCM routines checked and fixed for work with mmap_test
  - MIDI interface /dev/gusmidi extended
  - look to toplevel CHANGELOG for more details

v2.01a

  - 11.10.1996
  - noise channel support removed (it's user [application] thing)
  - code cleanups
  - some CODEC cleanups (MCE up/down - GUS MAX)
  - insgus recoded (now is used bison and flex for text scanning/parsing)
  - first support for 2.1.X kernels (not stable yet)

v2.00a

  -  9. 9.1996
  - many of code rearranged
  - initialization of GUS card totaly recoded
  - driver maybe more stable (unused interrupts handling added)
  - new interface /dev/gusmidi for MIDI support
  - extended sample support
    - real pan/volume envelopes (loop, sustain, fade)
    - real vibrato/tremolo modulations (sweep)
  - added instrument support 
  - instrument daemon added + support in the driver
  - insgus recoded for instrument daemon support
  - PCM routines recoded
    - non block PCM I/O support added
    - more than two logical fragments support added
    - all known USS's ioctl calls are now supported (maybe some have wrong implementation)
    - mmap() support added (experimental)
    - CODEC routines recoded
  - GF1 interrupt handler recoded
  - Plug & Play registers initialization code removed (system-kernel thing)
    - PnP owners should configure card via isapnp utility
  - InterWave
    - some extended initialization added
      - I hope that driver can now coexist with SoundBlaster cards
    - offset panning added (256 positions)
  - loopback control for CODEC's mixer added
  - PCM & SYNTH can work now together with GUS Classic card
  - massive UltraClick (tm) elimination
  - SA_INTERRUPT flag from setup of interrupt handler removed

v1.60b

  - 25. 3.1996
  - CODEC initialization again changed
  - mic input muting by PnP cards now works...

v1.60a

  - 24. 3.1996
  - support for Gravis UltraSound Plug & Play cards added
  - big changes in CODEC routines
  - card selection added (for remove of unused code)

v1.55e

  - 11. 3.1996
  - more driver cleanups (for 1.2.X kernels)

v1.55d

  -  9. 3.1996
  - more 64-bit cleanups
  - driver can be compiled under 1.2.X kernels (I hope..)

v1.55c

  -  3. 3.1996
  - some 64-bit cleanups for alpha systems
  - driver now can be compiled with kernel 1.3.70+

v1.55b

  - 25. 2.1996
  - some cleanups
  - seems to be trouble with big values for GF1's 2. timer (corrected?)

v1.55a

  - 18. 2.1996
  - little bug in mixer fixed (synth is now stereo)
  - MIDI VoxWare sequencer works now with playmidi but not well
  - support for GF1 patches added (not full)
  - global timer routines added for MIDI
  - GF1 timer handlers totaly recoded

v1.51a

  -  4. 1.1996
  - little problem with mixer initialization fixed
  - 16-bit Daughter Board support added (not yet tested)

v1.50b

  - 24.12.1995
  - /dev/audio,/dev/dsp,/dev/dsp16 bug fixed
  - /dev/audio now works for GUS MAX without loops
  - insgus utility now detects insmod exec error
  - DMA allocation routine recoded
    - DMA buffers are now allocated by request
  - /dev/gusinfo output modified
  - some other cleanups in PCM routines
  - full duplex playback & record may now work for GF1 chip, too...

v1.50a

  - 17.12.1995
  - probe/search of GUS card improved - all possible ports are checked right now
  - memory allocation functions changed
  - support for up to 8 GUS cards added
    - all routines recoded
    - many code cleanups
  - GF1 interrupt routine cleanups (bad ramp)
  - VoxWare sequencer emulator now also supports panning (stereo)

v1.30b

  -  7.12.1995
  - light CLI/STI for /dev/gus
  - -DVOXWARE_DEVS option added (thanks to Dan Merillat)

v1.30a

  -  1.12.1995
  - cleanups in ioctl's for /dev/gus device
    - incompatible with previous versions
  - cleanups in CLI/STI
  - echo command added
  - GUS's memory allocation routines changed
  - better sequencer compatibility with 'mod v0.81' player
  - code for mute added to mixer.c
  - full duplex playback & record - very alpha - maybe cause system hang
  - select function for pcm devices
  - autoconfiguration added

v1.25e

  - 30.10.1995
  - fixed compilation problem for kernels 1.3.37+ (already macro 'current')

v1.25d

  - 24.10.1995
  - fixed compilation problem for kernels 1.3.30+ (macro 'current')
  - new noise channel support

v1.25c

  -  7.10.1995
  - CODEC pcm cleanups - some end-clicks removed
  - noise channel support added
  - bug in GF1 reset function fixed
    - /dev/dsp works again well in 1.3.20+ for standard GUS cards
  - break & busy bug fixed for GF1 pcm

v1.25b

  -  8. 9.1995
  - timer cleanups in gf1_synth.c - /dev/gus

v1.25a

  -  3. 7.1995
  - cleanups in gf1_synth.c
  - sequencer code added for the support of VoxWare programs (gmod, s3mod)..

v1.23a

  - 20. 6.1995
  - some changes in pcm.c - DMA channels lock
  - major change in CODEC routines (GUS MAX) - timer handling
  - mixer default settings changed

v1.22b

  - 27. 5.1995
  - fixed bug (system hangup) caused by smooth pan function

v1.22a

  - 18. 5.1995
  - /dev/gusinfo device extended
  - abort fixed
  - added smooth change of pan positions - some other ultraclick removed

v1.21c

  -  5. 5.1995
  - sleep bug fixed

v1.21b

  -  4. 5.1995
  - some minor changes - no comment

v1.21a

  -  2. 5.1995
  - fast abort of /dev/gus added
  - some ioctls for time synchronization added (/dev/gus)
  - what_is_new "bug" fixed - probs with GF1 reset

v1.20b

  - 25. 4.1995
  - gus memory allocation routine recoded - optimalization for 16-bit waves
  - some minor changes in gf1_synth.c (new use of sleep and wakeup fcns)
  - new frequency type GUS_FREQ_TYPE_HZ

v1.20a

  - 31. 3.1995
  - XX.1-2.1995 - commercial break - because of the lack of time
  - small DMA bug fixed (big clicks removed)
  - Linux v1.1.83+ kernel support (irq routine prototype changed)
  - some code for OSF/1 added (non-functional)
  - work on OSF/1 version stopped - not enough time - probs with OSF/1 system
  - some detection problems fixed (GUS v3.4)
  - buffer for synth commands is now dynamically allocated (vmalloc)
  - PCM routines totally recoded - now are more realtime - DOOM works ok
  - full support for CODEC chip (GUS MAX only)
    - ALAW and ULAW compression works ok
    - ADPCM probs with freq > 22Khz and chip busy bit
  - volume ramping bug fixed in gf1_synth.c -> most ultraclicks fixed
  - version 2.0 of GF1 synth protocol
  - ICS mixer tested and small bug fixed.. Thanx to Assassin/Dimension
  - bug in download of 16-bit waves fixed
  - support for GUS cards v3.4 (without mixer) 
    - synth mixer now works correctly
  - some cleanups in mixer part
  - added mix mixer device - software control for gf1 volume
    (good if you want record GF1 output with CODEC chip)
    

v1.11b

  - 29.12.1994
  - problems with timer 2 fixed
  - some small changes in gf1_synth.c
  - some files renamed
  - port to OSF/1 v3.00 started !!!

v1.11a

  - 26.12.1994
  - debug free of 128Kb GUS memory disabled - startup is now quicker
  - /dev/gus changed (some ioctls added), synth protocol changed

v1.10a

  - 23.12.1994
  - initialization recoded again
    (IRQ & DMA & CODEC initialization - should be now ok - driver works
    now without VoxWare driver (tested only with GUS MAX!!!)
  - device.c totally recoded - some functions are moved to another files
  - /dev/gus is now capable to work with 16-bit waves (it wasn't tested!!!)
  - mixer compatible with VoxWare driver done (tested with aumix on GUS MAX)
    - ICS mixer wasn't tested !!
  - PCM driver added - in very alpha state - only playback & record via GF1 -
    version for CODEC in near future - Linux DOOM works, but not realtime :(
  - /dev/audio device wasn't tested !! - but it could work...
  - another minor changes in code

v1.02a

  -  1.12.1994
  - some small initialization bugs fixed (IRQ problems)
  - DMA transfers of waveforms to GUS DRAM added

v1.01a

  - many volume clicks fixed
  - timeout for sequencer queue added
  - downloading of 8-bit unsigned waveforms
  - ramping over GF1 IRQ

v1.00a

  - first release (30.10.1994)
