DOSSound driver documentation

Contents

1. Introduction
2. Controllers supported
3. Commandline options
4. Wave file player application
5. The Programming Interface - API

1. Introduction

DOSSOUND.COM is a sound driver supporting AC'97 audio controllers for real mode DOS.

For real mode DOS there is almost no driver available which supports the new audio
hardware on todays PC's. Most DOS audio applications are based on the Soundblaster
cards and their compatibles. These cards are no longer used on today's PC's.

The DOSSound driver provides a very simple interface to play PCM wave files with
AC'97 audio controllers and codecs. If you call DOSSound with a filename on the
command line it will play the file for you and terminate.

If you do not supply a file name it will install itself as a TSR driver. When installed as
a TSR driver using calls to interrupt 64h any application program can request a wave
file to be played, adjust the loudness etc. If an applications program specifies a wave file
to be played, DOSSound will return and continue to play the file in the background while
the application program can proceed.

DOSSound supports the wave file formats of 8bit mono, 16bit mono and 16bit stereo.
It will play uncompressed PCM files only. Use a utility like SOX to convert your audio files
into one of these formats.
Included is the DOS utility mp3towav.exe by Ray M. Ransom for your convenience. This
software is free for download on the internet. It is not covered by the enclosed licence and
copyright and property of Ray M. Ransom.

The objective of DOSSound is not to be a fully-featured audio player but to provide a simple
interface for application programs to use the AC'97 onboard audio controllers. This interface
can be used by games, audio players etc.

DOSSound does not provide a Soundblaster compatible interface! Most DOS programs
support only these cards. The programming interface of DOSSound is much simpler than
the Soundblaster inferface, so it should be very easy to adapt existing applications to this
interface. You just tell DOSSound what file on your disk you want to be played and
DOSSound will do the rest for you.

The memory requirements of DOSSound are relatively low. The driver itself needs
about 8kb plus 22k for its buffers.

Known problems:
- SIS will only play 44100 khz files at correct speed
- SIS: volume will not change if set in asynchronous mode
- 8bit stereo wave files are played with poor quality.
- VIA controllers of ID 3058 do not accept int 64h calls while playing
- DOSAMP balance will not work with Intel ICH2
- slightly distorted sound with soundblaster cards at 44100 16bit stereo

2. Controllers supported

DOSSound currently supports the following AC'97 controllers:
 
        Intel ICH-ICH7 and compatible (not ICH8-ICH10)
        VIA 82686, 8233, 8235 and 8237
        SIS 7012 controller
        
        untested:
        AMD 768, 8111
        nVidia NForce 1-3

High Definition Audio controllers are currently not supported.

To extend the audio hardware supported by DOSSound, there is also support for
Soundblaster cards and their emulations. DOSSound first checks whether a soundblaster
card is installed. If this is the case it will use that and not check for AC'97 controllers. It uses
I/O address 220h, interrupt 7, and DMA1 for 8bit and DMA5 for 16bit operation. The interrupt
used can be changed by the command line option /I5 to interrupt 5. This soundblaster
support was tested with a real Soundblaster 16 card, VDMSound, DOSBOX and the
DOS window of WinXP which emulates a SB 2.0 card. This emulation uses interrupt 5 so
you have to use the /I5 command line option with WinXP.
Since the WinXP Emulation does support mono files only DOSSound supports only mono
wave files for that. DOSSound will not load stereo files if it finds a SB 2.0 card and return
with the carry flag set. DOSAMP will report this as "file not found". I found that the WinXP
emulation does not work all that well and do not recommend using it.

3. Command line options

/Vxx
Sets the volume. /V02 for example sets both speakers to 2 or -3db. The value has to be
entered in HEX. Specifing /v0 will set it to loud, /V3F will mute the speakers. See AH=10
below too.

/Ix
Sets the interrupt for a Soundblaster card to either 5 or 7.

<filename> specify the file in the current directory or the full path to the file. This has to be
the last parameter on the command line.

Sample: "dossound.com /V08 yesterday.wav"

4. Wave file player application

Included in the package is DOSAMP.EXE which is a simple wave file player for DOS which
uses the DOSSound driver to play wave files. You first have to load the DOSSound.com
driver and then load DOSAMP.EXE. The source code for this player is included in the
samples directory.

DOSAMP will list the wave files in the current directory in a file selection box. It also lists the
subdirectories to allow to navigate to other directories. Use the cursor keys to select a file
and press enter.
Before selecting a new file you have to stop the current file. Also press stop if the file will not
start.
Pressing the letter in red color selects a function. So you have to press (and hold) the capital
"V" to increase the volume und the lowercase "v" to reduce the volume. You do not have to
press the ALT key here. ESC exits the DOSAMP application.

The player is primarily intended as a test application for DOSSound and not to compete with
other players.

5. Programming interface - API

Any application program can communicate with DOSSound via calls to interrupt 64h,
similar to the DOS function calls. The following calls are implemented:

AH=1 - Play Wave File

DS:DX = segment:offset of filename to play. The filename has to be an ASCIIZ string.
AL=0 play synchronously
AL=1 play asynchronously
return:
AL = handle of opened file
Carry flag set on return if error. Error codes in AL:
AL=1 if file not found
AL=2 if previous file still playing

DOSSound will load the file from disk and start playing it. If AL=0 is set, it will play the
file and return to the applcation after that. If AL=1 it returns to the application program
immediately and plays the file while running in the background.

You cannot load a new file while the previous file is still playing in the background. You
have to stop the previous file first with AH=21.

To support asynchronous mode DOSSound will hook into interrupts 8h, 13h, 1Ch and 28h.
It will play the file relying on these interrupts being called by the system or DOS. You need
a reasonably fast PC for this to work. Otherwise you have to use synchronous mode.

This way DOSSound will do multitasking in DOS, which is a single-tasking,
non-reentrant operating system. So the asynchronous mode is not as reliable
as synchronous mode.

DOSSound will hook the interrupts when it is loaded for the first time and unhook the
interrupts when it is terminated.
If you load another TSR program after DOSSound you first have to unload that before you
unload DOSSound since DOSSound checks whether the interrupts have been hooked
again after they have been hooked by DOSSound. If that is  the case, DOSSound will not
unhook them.

AH=3 Query Status

EBX = number of bytes played
ECX = total length in bytes of the wave file
DL = 8 or 16 for sample length of last file
DH = 1 for mono, 2 for stereo
SI = sample rate
ES:DI = far pointer to number of bytes played - 4 bytes
ES:DI+4 = far pointer to total number of bytes in wav file - 4 bytes
ES:DI+8 = far pointer to a flag indicating a file is currently playing - 1 byte
ES:DI+9 = far pointer to a flag indicating pause is set - 1 byte
ES:DI+10 = far pointer to a flag indicating loop is set - 1 byte
ES:DI+11 = far pointer to number of buffer currently playing
These pointers can be read without calling int 64h

If EBX=ECX or ES:DI=ES:DI+4 the file has been played completely. The values will be
overwritten when a new file has been loaded using AH=1.

AH=10h - Specify Volume

BX = volume for the left and right speaker in hex
A value of zero provides the maximum volume. The value of 0101h will reduce the
volume by -1,5 db for both speakers while 0208h will reduce the volume for the left
speaker by -3 db and for the right speaker by -12 db.

1Fh is the maximum attenuation. So 1F1Fh will virtually mute the speakers.

Setting the volume not supported for Soundblaster cards.

AH=20h - Pause

BX=0 - resume a paused AC'97 controller
BX=1 - pause AC'97 controller

AH=21h - Stop

Terminates the AC'97 controller playing the wave file and closes the file.

AH=22h - Loop

BX=0 - stop loop
BX=1 - restart playing the audio file each time the end of file is reached

AH=30h - Read Codec Register Value

DX = number of codec register to return
AX or EAX = value currently stored in requested codec register
Consult the AC'97 specifications or a data sheet of the codec manufacturer
for an explanation of these registers.

This function is not supported for Soundblaster cards.

AH=31h - Write Codec Register Value

DX = number of codec register to write to
CX = value to store in requested codec register

This function is not supported for Soundblaster cards.

AH=40h - Return Vendor/Device

BX = AC'97 vendor ID
CX = AC'97 device ID
DX = 6D50h DOSSound ID.

For Soundblaster cards BX gives the major version and CX gives the minor version.

The returned values are the PCI ID's of the audio controller installed.
The value in DX can serve as a simple check whether DOSSound is installed.

AH=50h - Return segments of internal buffers

BX = Segment address of first internal buffer
CX = Size of buffers in segments. So a returned value of 280hex means 2800hex
bytes buffer size. The segment address of the second buffer is BX+CX.

There are two buffers of the specified size. The second buffer is directly following the first
in memory. Only the segment address is specified, the offset is always zero.

AH=51h - Start playing with buffers loaded externally

BX = Sample rate of audio data. This data has to be signed 16 bit stereo PCM data.

The functions 50h/51h are designed to allow an application program to load the internal
buffers with PCM data and get DOSSound play the data in the buffers. This has to be
raw PCM data without a file header.

The application first queries the location and size of the buffers with the AH=50h function.
Then it calls function AH=3 to get the far pointer to the number of the buffer currently
playing. This number is at address ES:DI+11.

Then it loads both buffers with PCM data and uses function AH=51h to start DOSSound
playing the PCM data in the buffers. The application has to monitor the number of the buffer
currently playing. This can be either 0 or 1. If that number changes, the application has to fill
the buffer currently not playing with new PCM data. Partially filled buffers will be padded
with zeros (00h) since DOSSound clears the buffer after it is played. When done the application stops DOSSound from playing using function AH=21h. 

12th May 2009 Georg Potthast