This document is provided on an "as-is" basis, and its author makes no warranty or representation, express or implied, with respect to its quality performance or fitness for a particular purpose. In no event will the author of this document be liable for direct, indirect, special, incidental, or consequential damages arising out of the use or inability to use the information contained within. Use of this document is at your own risk.

This file may be used and copied freely so long as the applicable copyright notices are retained, and no modifications are made to the text of the document. No money shall be charged for its distribution beyond reasonable shipping, handling and duplication costs, nor shall proprietary changes be made to this document so that it cannot be distributed freely. This document may not be included in published material or commercial packages without the written consent of its author.

Two of the most popular sound cards for the IBM-PC, the AdLib and the Sound Blaster, suffer from a real dearth of clear documentation for programmers. AdLib Inc. and Creative Labs, Inc. both sell developers' kits for their sound cards, but these are expensive, and (in the case of the Sound Blaster developers' kit) can be extremely cryptic.

This document is intended to provide programmers with a FREE source of information about the programming of these sound cards.

The information contained in this document is a combination of information found in the Sound Blaster Software Developer's Kit, and that learned by painful experience. Some of the information may not be valid for AdLib cards; if this is so, I apologize in advance.

Please note that numbers will be given in hexadecimal, unless otherwise indicated. If a number is written out longhand (sixteen instead of 16) it is in decimal.

The sound card is programmed by sending data to its internal registers via its two I/O ports:

0388 (hex) - Address/Status port (R/W)
0389 (hex) - Data port (W/O)

The Sound Blaster Pro is capable of stereo FM music, which is accessed in exactly the same manner. Ports 0220 and 0221 (hex) are the address/ data ports for the left speaker, and ports 0222 and 0223 (hex) are the ports for the right speaker. Ports 0388 and 0389 (hex) will cause both speakers to output sound.

The sound card possesses an array of two hundred forty-four registers; to write to a particular register, send the register number (01-F5) to the address port, and the desired value to the data port.

After writing to the register port, you must wait twelve cycles before sending the data; after writing the data, eighty-four cycles must elapse before any other sound card operation may be performed.

The AdLib manual gives the wait times in microseconds: three point three (3.3) microseconds for the address, and twenty-three (23) microseconds for the data.

AdLib suggested that the delays be produced by reading the register port six times after writing to the register port, and reading the register port thirty-five times after writing to the data port. With the advent of much faster machines, however, this method is not necessarily reliable.

The sound card registers are write-only.

The address port also functions as a sound card status byte. To retrieve the sound card's status, simply read port 388. The status byte has the following structure:

7	6	5	4	3	2	1	0
both timers	timer 1	timer 2	unused

Bit 7 -	set if either timer has expired.
6 -	set if timer 1 has expired.
5 -	set if timer 2 has expired.

The following table shows the function of each register in the sound card. Registers will be explained in detail after the table. Registers not listed are unused.

Address	Function
01	Test LSI / Enable waveform control
02	Timer 1 data
03	Timer 2 data
04	Timer control flags
08	Speech synthesis mode / Keyboard split note select
20..35	Amp Mod / Vibrato / EG type / Key Scaling / Multiple
40..55	Key scaling level / Operator output level
60..75	Attack Rate / Decay Rate
80..95	Sustain Level / Release Rate
A0..A8	Frequency (low 8 bits)
B0..B8	Key On / Octave / Frequency (high 2 bits)
BD	AM depth / Vibrato depth / Rhythm control
C0..C8	Feedback strength / Connection type
E0..F5	Wave Select

The groupings of twenty-two registers (20-35, 40-55, etc.) have an odd order due to the use of two operators for each FM voice. The following table shows the offsets within each group of registers for each operator.

Channel	1	2	3	4	5	6	7	8	9
Operator 1	00	01	02	08	09	0A	10	11	12
Operator 2	03	04	05	0B	0C	0D	13	14	15

Thus, the addresses of the attack/decay bytes for channel 3 are 62 for the first operator, and 65 for the second. (The address of the second operator is always the address of the first operator plus three).

To further illustrate the relationship, the addresses needed to control channel 5 are:

29	Operator 1	AM/VIB/EG/KSR/Multiplier
2C	Operator 2	AM/VIB/EG/KSR/Multiplier
49	Operator 1	KSL/Output Level
4C	Operator 2	KSL/Output Level
69	Operator 1	Attack/Decay
6C	Operator 2	Attack/Decay
89	Operator 1	Sustain/Release
8C	Operator 2	Sustain/Release
A4		Frequency (low 8 bits)
B4		Key On/Octave/Frequency (high 2 bits)
C4		Feedback/Connection Type
E9	Operator 1	Waveform
EC	Operator 2	Waveform

Bytes E0-F5	Waveform Select 7 6 5 4 3 2 1 0 unused Waveform Select bits 1-0 - When bit 5 of address 01 is set, the output waveform will be distorted according to the waveform indicated by these two bits:

According to the AdLib manual, the 'official' method of checking for a sound card is as follows:

1. Reset both timers by writing 60h to register 4.
2. Enable the interrupts by writing 80h to register 4.
   NOTE: this must be a separate step from number 1.
3. Read the status register (port 388h). Store the result.
4. Write FFh to register 2 (Timer 1).
5. Start timer 1 by writing 21h to register 4.
6. Delay for at least 80 microseconds.
7. Read the status register (port 388h). Store the result.
8. Reset both timers and interrupts (see steps 1 and 2).
9. Test the stored results of steps 3 and 7 by ANDing them with E0h. The result of step 3 should be 00h, and the result of step 7 should be C0h. If both are correct, an AdLib-compatible board is installed in the computer.

Many people have asked me, upon reading this document, what the proper register values should be to make a simple sound. Well, here they are.

First, clear out all of the registers by setting all of them to zero. This is the quick-and-dirty method of resetting the sound card, but it works. Note that if you wish to use different waveforms, you must then turn on bit 5 of register 1. (This reset need be done only once, at the start of the program, and optionally when the program exits, just to make sure that your program doesn't leave any notes on when it exits.)

Now, set the following registers to the indicated value:

To turn the voice off, set register B0h to 11h (or, in fact, any value which leaves bit 5 clear). It's generally preferable, of course, to induce a delay before doing so.

Thanks are due to the following people:

Ezra M. Dreisbach (ed10+@andrew.cmu.edu), for providing the information about the recommended port write delay from the AdLib manual, and the 'official' method of detecting an AdLib-compatible sound card.

Nathan Isaac Laredo (gt7080a@prism.gatech.edu), for providing the port numbers for stereo sound on the Sound Blaster Pro.