Sound Blaster Driver v1.6
by Pancheri Paolo (980812)

General Index
-------------

	1. Using the Sound Blaster Driver
   	1.1 Detect the I/O base address and the IRQ number
   	1.2 Initialize the driver
      1.3 Load and play samples
      1.4 Remove the driver
   2. Sound Blaster cards capabilities
   	2.1 Sound Blaster 1.0/1.5
      2.2 Sound Blaster 2.0
      2.3 Sound Blaster Pro
      2.4 Sound Blaster 16
   3. Result codes
   4. Functions reference
      4.1 sb_dsp_reset()
      4.2 sb_dsp_write()
      4.3 sb_dsp_read()
      4.4 sb_speaker_on()
      4.5 sb_speaker_off()
      4.6 sb_dsp_get_version()
      4.7 sb_get_model_name()
      4.8 sb_interrupt_number()
      4.9 sb_dsp_detect_base_address()
      4.10 sb_dsp_detect_irq_number()
      4.11 sb_dsp_detect_dma_channel_8()
      4.12 sb_set_dma_channel_8()
      4.13 sb_install_driver()
      4.14 sb_remove_driver()
      4.15 sb_get_driver_version()
      4.16 sb_set_max_voices()
      4.17 sb_reduce_amplitude()
      4.18 sb_free_sample()
      4.19 sb_play_sample()
      4.20 sb_stop_sample()
      4.21 sb_read_raw()
      4.22 sb_read_wav()
      4.23 sb_read_sample()
      4.24 sb_mixer_register_set()
      4.25 sb_mixer_register_get()
	5. Revision Information
   	5.1 v1.0
      5.2 v1.1
      5.3 v1.2
      5.4 v1.5
      5.5 v1.6
   6. Glossary of Terms
   7. Acknowledgements

1. Using the Sound Blaster Driver
---------------------------------

   1.1 Detect the I/O base address and the IRQ number
		If you wanna know the I/O base address and the IRQ number of the Sound Blaster,
      use these functions:

			BOOL	sb_dsp_detect_base_address(WORD *base_address);
			BOOL	sb_dsp_detect_irq_number(BYTE *irq_number);

      The first function will fail only if no Sound Blaster card is installed. The DMA
      channel is defaulted to 1, but you can change this value using this function:

         void	sb_set_dma_channel_8(BYTE dma_channel_8);

	1.2 Initialize the driver
   	The library automagically detects the I/O base address of the Sound Blaster card
      and the IRQ used for the DMA transfer. The DMA channel, instead, is supposed to
      be 1, because the XT architecture allows only this channel free for other use.
      So to initialize and install the driver call the function:

         BOOL	sb_install_driver(WORD	frequency, BOOL use_stereo);

      The function will return the result code (see section 3: Result codes).
      The 'frequency' parameter indicates the sampling rate, and 'use_stereo'
      indicates if the driver should work in stereo or mono mode.

   1.3 Load and play samples
   	To load a sample from a file, you need a SAMPLE variable. Next call one of these
      functions:

			BOOL	sb_read_raw(char *filename, SAMPLE *sample);
			BOOL	sb_read_wav(char *filename, SAMPLE *sample);
			BOOL	sb_read_sample(char *filename, SAMPLE *sample);

      The function sb_read_sample() detect if the file is .RAW or .WAV from the
      extension, so is better that sb_read_raw() and sb_read_wav(). The memory needed
      for the data is auto allocated by the functions, so you must call the function

         void	sb_free_sample(SAMPLE *sample);

      to release it.

      When the driver is installed, to play a sample call the function:

         BOOL	sb_play_sample(
         	SAMPLE *sample,
         	BOOL loop,
         	void (*callback)(BYTE id),
         	BYTE *id);

		You can pass NULL for both 'callback' and 'id' parameters.
      If there are other samples in playing, these will be mixed in real time.
      Is better to call the function (4.17: sb_reduce_amplitude()) to reduce the
      clip distorsion.

   1.4 Remove the driver
   	To remove the Sound Blaster driver from memory, call the function:

         BOOL	sb_remove_driver(void);

2. Sound Blaster cards capabilities
-----------------------------------
There are a list of the capabilities of the Sound Blaster cards supported for now
by the Sound Blaster Driver:

   	2.1 Sound Blaster 1.0/1.5
      	Min mono sampling rate (8 bit): 		4000
         Max mono sampling rate (8 bit): 		22222
         Min stereo sampling rate (8 bit):   -
         Max stereo sampling rate (8 bit):   -
         Auto DMA mode support: 					no
         High Speed mode support: 				no
         Stereo support:							no
         16 bit sample:								no

      2.2 Sound Blaster 2.0
      	Min mono sampling rate (8 bit): 		4000
         Max mono sampling rate (8 bit): 		45454
         Min stereo sampling rate (8 bit):   -
         Max stereo sampling rate (8 bit):   -
         Auto DMA mode support: 					yes
         High Speed mode support: 				yes
         Stereo support:							no
         16 bit sample:								no

		2.3 Sound Blaster Pro
      	Min mono sampling rate (8 bit):		4000
         Max mono sampling rate (8 bit):		45454
         Min stereo sampling rate (8 bit):   4000
         Max stereo sampling rate (8 bit):   22727
         Auto DMA mode support:					yes
         High Speed mode support: 				yes
         Stereo support:							yes
         16 bit sample:								no

		2.4 Sound Blaster 16
      	Min mono sampling rate (8 bit):		4000
         Max mono sampling rate (8 bit):		45454
         Min stereo sampling rate (8 bit):   4000
         Max stereo sampling rate (8 bit):   45454
         Auto DMA mode support:					yes
         High Speed mode support: 				yes
         Stereo support:							yes
         16 bit sample:								yes

3. Result codes
---------------

	SB_OK       				0
   	Succesfull (no errors).

	SB_RESET_DSP	   		1
   	Cannot reset the DSP. If you call the function sb_dsp_reset(), surely the
      base_address is wrong.

	SB_DETECT_DSP				2
      Cannot detect the SB DSP I/O base address. Check if there are a Sound Blaster
      card installed on the system.

	SB_NOT_INITIALIZED		3
      SB Library not initialized. Try to call the function sb_dsp_detect_base_address()
      before the function that return this code.

	SB_INVALID_IRQ				4
      Invalid IRQ number. You surely made a call to the function sb_interrupt_number()
      with an invalid IRQ number. Only IRQ 2, 3, 5, 7, 10 are valid.

	SB_DOS_MEMORY				5
      Cannot allocate DOS memory buffer. The driver cannot allocate a small memory
      buffer in the real memory area for DMA transfers.

	SB_SAMPLE_RATE				6
      Sample rate out of range (see section 2: Sound Blaster cards capabilities).

	SB_OPEN						7
      Cannot open a file. Maybe you try to load a sample file that doesn't exist.

	SB_READ						8
      Cannot read from a file.

	SB_MEMORY					9
      Cannot allocate memory in the protected memory area.

	SB_TOO_MANY_VOICES		10
      Diver are playing too many voices. If you call the function sb_play_sample(),
      this result code indicates that the driver is currently playing the maximum
      number of voices, and can't play more.

	SB_INVALID_FILE			11
      Invalid (sound) file. Maybe you call sb_load_sample() and the file isn't a
      sound file.

   SB_USE_STEREO				12
      Stereo mode not supported. A Sound Blaster Pro or better required for stereo
      mode.

4. Functions reference
----------------------

	4.1 sb_dsp_reset()
   	Reset the DSP

   		BOOL	sb_dsp_reset(WORD base_address);

      'base_address'(in): the base address of the DSP
      'return'(out): SB_OK - DSP succesfull resetted
      					SB_RESET_DSP - cannot reset the DSP

	4.2 sb_dsp_write()
   	Write a value to the DSP

   		BOOL	sb_dsp_write(BYTE value);

      'value'(in): value to write to the DSP
      'return'(out): SB_OK - value successfull send to the DSP
      					SB_NOT_INITIALIZED - the base address of the DSP isn't setted.
      						Call sb_dsp_detect_base_address()

	4.3 sb_dsp_read()
   	Read a value from the DSP

			BOOL	sb_dsp_read(BYTE *value);

      'value'(out): value readed from the DSP
      'return'(out): SB_OK - value successfully readed from the DSP
      					SB_NOT_INITIALIZED - the base address of the DSP isn't setted.
      						Call sb_dsp_detect_base_address()

	4.4 sb_speaker_on()
   	Turn the speaker on

   		BOOL	sb_speaker_on(void);

      'return'(out): SB_OK - speaker turned on
      					SB_NOT_INITIALIZED - the base address of the DSP isn't setted.
      						Call sb_dsp_detect_base_address()

	4.5 sb_speaker_off()
   	Turn the speaker off

			BOOL	sb_speaker_off(void);

      'return'(out): SB_OK - speaker turned off
      					SB_NOT_INITIALIZED - the base address of the DSP isn't setted.
      						Call sb_dsp_detect_base_address()

	4.6 sb_dsp_get_version()
   	Read the version of the DSP

			BOOL	sb_dsp_get_version(WORD *version);

      'version'(out): the version of the DSP
			Sound-Blaster AWE32   version >= 0x040C
			Sound-Blaster 16      version >= 0x0400
			Sound-Blaster Pro     version >= 0x0300
			Sound-Blaster 2.0     version >= 0x0201
			Sound-Blaster 1.0/1.5 else
      'return'(out): SB_OK - DSP version successfully readed
      					SB_NOT_INITIALIZED - the base address of the DSP isn't setted.
      						Call sb_dsp_detect_base_address()

	4.7 sb_get_model_name()
   	Get the name of the Sound Blaster model (see 4.6: sb_dsp_get_version())

			BOOL	sb_get_model_name(char *name);

      'name'(out): the name of the Sound Blaster model
      'return'(out): SB_OK - DSP version successfully readed
      					SB_NOT_INITIALIZED - the base address of the DSP isn't setted.
      						Call sb_dsp_detect_base_address()

	4.8 sb_interrupt_number()
   	Get the number of the interrupt used by the IRQ

			BOOL	sb_interrupt_number(BYTE irq_number, BYTE *interrupt_number);

      'irq_number'(in): IRQ number (of the SB)
      'interrupt_number'(out): interrupt use by the IRQ
      'return'(out): SB_INVALID_IRQ - valid IRQ numbers are 2, 3, 5, 7, 10
                     SB_OK - ...

	4.9 sb_dsp_detect_base_address()
   	Detect the base address of the Sound Blaster DSP

			BOOL	sb_dsp_detect_base_address(WORD *base_address);

      'base_address'(out): the base address of the DSP
      'return'(out): SB_DETECT_DSP - maybe there are no Sound Blaster installed
      					SB_OK - DSP base address successfully readed

	4.10 sb_dsp_detect_irq_number()
   	Detect the number of the IRQ used by the DSP

			BOOL	sb_dsp_detect_irq_number(BYTE *irq_number);

		'irq_number'(out): the number of the IRQ used by the DSP
      'return'(out): SB_INVALID_IRQ - the IRQ number can be detected
                     SB_OK - IRQ number succesfully detected

	4.11 sb_dsp_detect_dma_channel_8()
   	If the sound card is a Sound Blaster 16 or better, this function will detect the
      DMA channel for 8 bit transfers, else only return the number 1. If your Sound
      Blaster isn't SB16 or better and use another 8 bit DMA channel, call the
      function (4.12: sb_set_dma_channel_8).

			BOOL	sb_dsp_detect_dma_channel_8(BYTE	*dma_channel_8);

      'dma_channel_8'(out): 1
      'return'(out): SB_OK

	4.12 sb_set_dma_channel_8()
   	Change the default value of the 8 bit DMA channel.

			void	sb_set_dma_channel_8(BYTE dma_channel_8);

      'dma_channel_8'(in): new 8 bit DMA channel

	4.13 sb_install_driver()
   	Install the Sound Blaster Driver. You can specify the sampling rate and
   	mono/stereo mode (see 2: Sound Blaster cards capabilities).

      	BOOL	sb_install_driver(WORD	frequency, BOOL use_stereo);

      'frequency'(in): sampling rate
      'use_stereo'(in): FALSE for mono, TRUE for stereo
      'return'(out): SB_DETECT_DSP - cannot detect the DSP base address
      					SB_INVALID_IRQ - the IRQ number can be detected
                     SB_USE_STEREO - the Sound Blaster card doesn't support stereo
                     SB_DOS_MEMORY - cannot allocate the DOS memory buffer
                     SB_MEMORY - cannot allocate virtual memory buffer
                     SB_SAMPLE_RATE - sampling rate out of range
                     SB_OK - Sound Blaster Driver successfully installed

	4.14 sb_remove_driver()
   	Removes the Sound Blaster Driver

			BOOL	sb_remove_driver(void);

      'return'(out): SB_NOT_INITIALIZED - the driver isn't installed
      					SB_OK - driver removed

   4.15 sb_get_driver_version()
   	Get the version of the driver

			WORD	sb_get_driver_version(void);

      'return'(out): version of the driver (see 5: Revision information)

	4.16 sb_set_max_voices()
   	Set the max number of voices that can be mixed in the same time

			void	sb_set_max_voices(BYTE max_voices);

      'max_voices'(in): max number of voices

	4.17 sb_reduce_amplitude()
   	Reduces the amplitude of the sample

			void	sb_reduce_amplitude(SAMPLE *sample);

      If you should play more that one sample in the same time, you can have a bit
      distorsion. To reduce the distorsion, is possible to reduce the amplitude of
      the samples. This method will also reduce the volume of the sample, but you
      will have a better sound quality.

      'sample'(in): the sample to reduce

	4.18 sb_free_sample()
   	Release the memory used by the sample

			void	sb_free_sample(SAMPLE *sample);

      'sample'(in): the sample to release

	4.19 sb_play_sample()
   	Play a sample

			BOOL	sb_play_sample(
				SAMPLE *sample,
				BOOL loop,
				void (*callback)(BYTE id),
				BYTE *id);

      Is better to call sb_reduce_amplitude() to reduce clip distorsion.

      'sample'(in): the sample to play
      'loop'(in): if you pass TRUE, the sample will be looped
      'callback'(in): when the sample reach the end, the callback function will
      	be called. You can pass no function (NULL).
      'id'(in): the ID of the sample. Use it with the callback function and the
      	(4.:sb_stop_sample()) function.
      'return'(out): SB_NOT_INITIALIZED - the Sound Blaster Driver is not installed
                     SB_TOO_MANY_VOICES - max number of voices reached
                     SB_OK - the sample will be played

	4.20 sb_stop_sample()
   	Stop playing a sample

      	BOOL	sb_stop_sample(BYTE id);

      When you call this function, the sample you specify will be stopped.

      'id'(in): the ID of the sample to stop
      'return'(out): SB_NO_SAMPLE - no sample with this id
      					SB_OK - the sample will be stopped

	4.21 sb_read_raw()
   	Read a sample from a raw file

			BOOL	sb_read_raw(char *filename, SAMPLE *sample);

		'filename'(in): name of the RAW file
      'sample'(in): is the function that allocate the space for the sample.
      					Use (4.18: sb_free_sample()) to release the sample
		'return'(out): SB_OPEN - cannot open the file
                     SB_MEMORY - cannot allocate memory for the sample
                     SB_READ - error reading from the file
                     SB_OK - sample successfully readed

	4.22 sb_read_wav()
   	Read a sample from a WAV file

			BOOL	sb_read_wav(char *filename, SAMPLE *sample);

		'filename'(in): the name of the WAV file
      'sample'(in): is the function that allocate the space for the sample.
      					Use (4.18: sb_free_sample()) to release the sample
		'return'(out): SB_OPEN - cannot open the file
                     SB_MEMORY - cannot allocate memory for the sample
                     SB_READ - error reading from the file
                     SB_INVALID_FILE - the file isn't in the WAV format
                     SB_OK - sample successfully readed

	4.23 sb_read_sample()
   	This function detect the file format from the extension, and call
   	(4.20: sb_read_raw()) or (4.21: sb_read_wav()).

			BOOL	sb_read_sample(char *filename, SAMPLE *sample);

		'filename'(in): the name of the WAV or RAW file
      'sample'(in): is the function that allocate the space for the sample.
      					Use (4.18: sb_free_sample()) to release the sample
		'return'(out): SB_OPEN - cannot open the file
                     SB_MEMORY - cannot allocate memory for the sample
                     SB_READ - error reading from the file
                     SB_INVALID_FILE - format unknow (only .RAW and .WAV are supported)
                     						or the file isn't in the WAV format (for .WAV)
                     SB_OK - sample successfully readed

	4.24 sb_mixer_register_set()
   	Set a mixer register

			BOOL	sb_mixer_register_set(BYTE index, BYTE value);

		'index'(in): the number of the Sound Blaster mixer register
      'value'(in): the value to write in the register
      'return'(out): SB_NOT_INITIALIZED - the base address of the DSP isn't setted.
      					SB_OK - value succesfully wrote

	4.25 sb_mixer_register_get()
      Get the value of a mixer register

         BOOL	sb_mixer_register_get(BYTE index, BYTE *value);

		'index'(in): the number of the Sound Blaster mixer register
      'value'(out): the value of the register
      'return'(out): SB_NOT_INITIALIZED - the base address of the DSP isn't setted.
      					SB_OK - value succesfully readed

5. Revision information
-----------------------

	5.1 - v1.0 (980812)
   	First version of the library
      Support for SB 1.0 - 1.5
      8 bit, mono, max. 22222 Hz, Single Cycle DMA Transfer
      Base Address, IRQ autodetection. DMA channel default to 1
      No real-time mixing (only one sample at time)
      Read only .RAW files

	5.2 - v1.1 (980813)
   	Support for SB 2.0
      8 bit, mono, max 45454 Hz (High Speed), A/I DMA Transfer
      Base Address, IRQ autodetection. DMA channel default to 1
      Real time mixing (division method, reduces total amplitude)
      Read .RAW and .WAV files

   5.3 - v1.2 (980814)
   	Support for SB Pro
      Stereo mode support -> not tested. I've a SB16, and the programming mode
      is different from SB Pro.

   5.4 - v1.5 (980814)
   	Support for SB 16
      8 bit, mono/stereo, max 45454 Hz (High Speed) both mono and stereo mode,
      A/I DMA Transfer. Base Address, IRQ autodetection. DMA channel default to 1.
      Real time mixing (division method, reduces total amplitude). Can play stereo
      sample in mono mode and mono samples in stereo mode.
      Read .RAW and .WAV files
   5.5 - v1.6 (980819)
   	Same as v1.5 with some bug fixed.
      Real time mixing now works good.
      Samples can looped. Added a callback function.

6. Glossary of Terms
--------------------

   Auto DMA mode (A/I)
   	This mode increase the quality of the playback, because permit to eliminate
      the 'click' (or noise).

   High Speed mode
   	This mode allows to do an high frequency samplig rate (>23Hz).

   RAW files
   	When a file contains only raw data, without headers of any sort, it's called
      RAW file

7. Acknowledgements
-------------------

   Sound Blaster Programming Information v0.90, Andr Baresel - Craig Jackson
   Programming the SoundBlaster DSP, Written for the PC-GPE by Mark Feldman
   INTRO TO DMA by Draeden of VLA

   Special thanks to	Jason Tenn and DiSCoNNeCT, that helped my about mixing.
