]> 4ch.mooo.com Git - 16.git/blob - 16/PCGPE10/ADLIB.TXT
reverted my open watcom to 1.9 an recompiled everything~
[16.git] / 16 / PCGPE10 / ADLIB.TXT
1 \r
2                       Programming the AdLib/Sound Blaster\r
3                                 FM Music Chips\r
4                            Version 2.0 (24 Feb 1992)\r
5 \r
6                   Copyright (c) 1991, 1992 by Jeffrey S. Lee\r
7 \r
8                                jlee@smylex.uucp\r
9 \r
10 \r
11  \r
12                         Warranty and Copyright Policy\r
13 \r
14      This document is provided on an "as-is" basis, and its author makes\r
15      no warranty or representation, express or implied, with respect to\r
16      its quality performance or fitness for a particular purpose.  In no\r
17      event will the author of this document be liable for direct, indirect,\r
18      special, incidental, or consequential damages arising out of the use\r
19      or inability to use the information contained within.  Use of this\r
20      document is at your own risk.\r
21 \r
22      This file may be used and copied freely so long as the applicable\r
23      copyright notices are retained, and no modifications are made to the\r
24      text of the document.  No money shall be charged for its distribution\r
25      beyond reasonable shipping, handling and duplication costs, nor shall\r
26      proprietary changes be made to this document so that it cannot be\r
27      distributed freely.  This document may not be included in published\r
28      material or commercial packages without the written consent of its\r
29      author.\r
30 \r
31 \r
32 \r
33                                    Overview\r
34 \r
35      Two of the most popular sound cards for the IBM-PC, the AdLib and the\r
36      Sound Blaster, suffer from a real dearth of clear documentation for \r
37      programmers.  AdLib Inc. and Creative Labs, Inc. both sell developers'\r
38      kits for their sound cards, but these are expensive, and (in the case\r
39      of the Sound Blaster developers' kit) can be extremely cryptic.\r
40 \r
41      This document is intended to provide programmers with a FREE source\r
42      of information about the programming of these sound cards.\r
43 \r
44      The information contained in this document is a combination of\r
45      information found in the Sound Blaster Software Developer's Kit, and\r
46      that learned by painful experience.  Some of the information may not\r
47      be valid for AdLib cards; if this is so, I apologize in advance.\r
48 \r
49      Please note that numbers will be given in hexadecimal, unless otherwise\r
50      indicated.  If a number is written out longhand (sixteen instead of 16)\r
51      it is in decimal.\r
52 \r
53  |   Changes from Version 1 of the file will be indicated by the use of change\r
54  |   bars in the left-hand margin.\r
55 \r
56 \r
57 \r
58                          Chapter One - Sound Card I/O\r
59 \r
60      The sound card is programmed by sending data to its internal registers\r
61      via its two I/O ports:\r
62 \r
63              0388 (hex) - Address/Status port  (R/W)\r
64              0389 (hex) - Data port            (W/O)\r
65 \r
66  |   The Sound Blaster Pro is capable of stereo FM music, which is accessed\r
67  |   in exactly the same manner.  Ports 0220 and 0221 (hex) are the address/\r
68  |   data ports for the left speaker, and ports 0222 and 0223 (hex) are the\r
69  |   ports for the right speaker.  Ports 0388 and 0389 (hex) will cause both\r
70  |   speakers to output sound.\r
71 \r
72      The sound card possesses an array of two hundred forty-four registers;\r
73      to write to a particular register, send the register number (01-F5) to\r
74      the address port, and the desired value to the data port.\r
75 \r
76      After writing to the register port, you must wait twelve cycles before \r
77      sending the data; after writing the data, eighty-four cycles must elapse\r
78      before any other sound card operation may be performed.\r
79 \r
80  |   The AdLib manual gives the wait times in microseconds: three point three\r
81  |   (3.3) microseconds for the address, and twenty-three (23) microseconds\r
82  |   for the data.\r
83  |\r
84  |   The most accurate method of producing the delay is to read the register\r
85  |   port six times after writing to the register port, and read the register\r
86  |   port thirty-five times after writing to the data port.\r
87 \r
88      The sound card registers are write-only.\r
89 \r
90      The address port also functions as a sound card status byte.  To \r
91      retrieve the sound card's status, simply read port 388.  The status \r
92      byte has the following structure:\r
93 \r
94               7      6      5      4      3      2      1      0\r
95           +------+------+------+------+------+------+------+------+\r
96           | both | tmr  | tmr  |              unused              |\r
97           | tmrs |  1   |  2   |                                  |\r
98           +------+------+------+------+------+------+------+------+\r
99 \r
100           Bit 7 - set if either timer has expired.\r
101               6 - set if timer 1 has expired.\r
102               5 - set if timer 2 has expired.\r
103 \r
104 \r
105 \r
106                        Chapter Two - The Registers\r
107 \r
108 The following table shows the function of each register in the sound \r
109 card.  Registers will be explained in detail after the table.  Registers\r
110 not listed are unused.\r
111 \r
112    Address      Function\r
113    -------      ----------------------------------------------------\r
114      01         Test LSI / Enable waveform control\r
115      02         Timer 1 data\r
116      03         Timer 2 data\r
117      04         Timer control flags\r
118      08         Speech synthesis mode / Keyboard split note select\r
119    20..35       Amp Mod / Vibrato / EG type / Key Scaling / Multiple\r
120    40..55       Key scaling level / Operator output level\r
121    60..75       Attack Rate / Decay Rate\r
122    80..95       Sustain Level / Release Rate\r
123    A0..A8       Frequency (low 8 bits)\r
124    B0..B8       Key On / Octave / Frequency (high 2 bits)\r
125      BD         AM depth / Vibrato depth / Rhythm control\r
126    C0..C8       Feedback strength / Connection type\r
127    E0..F5       Wave Select\r
128 \r
129 The groupings of twenty-two registers (20-35, 40-55, etc.) have an odd\r
130 order due to the use of two operators for each FM voice.  The following\r
131 table shows the offsets within each group of registers for each operator.\r
132 \r
133 \r
134    Channel        1   2   3   4   5   6   7   8   9\r
135    Operator 1    00  01  02  08  09  0A  10  11  12\r
136    Operator 2    03  04  05  0B  0C  0D  13  14  15\r
137 \r
138 Thus, the addresses of the attack/decay bytes for channel 3 are 62 for\r
139 the first operator, and 65 for the second.  (The address of the second\r
140 operator is always the address of the first operator plus three).\r
141 \r
142 To further illustrate the relationship, the addresses needed to control\r
143 channel 5 are:\r
144 \r
145     29 - Operator 1  AM/VIB/EG/KSR/Multiplier\r
146     2C - Operator 2  AM/VIB/EG/KSR/Multiplier\r
147     49 - Operator 1  KSL/Output Level\r
148     4C - Operator 2  KSL/Output Level\r
149     69 - Operator 1  Attack/Decay\r
150     6C - Operator 2  Attack/Decay\r
151     89 - Operator 1  Sustain/Release\r
152     8C - Operator 2  Sustain/Release\r
153     A4 -             Frequency (low 8 bits)\r
154     B4 -             Key On/Octave/Frequency (high 2 bits)\r
155     C4 -             Feedback/Connection Type\r
156     E9 - Operator 1  Waveform\r
157     EC - Operator 2  Waveform\r
158 \r
159 \r
160 \r
161                        Explanations of Registers\r
162 \r
163 Byte 01 - This byte is normally used to test the LSI device.  All bits\r
164           should normally be zero.  Bit 5, if enabled, allows the FM \r
165           chips to control the waveform of each operator.\r
166 \r
167              7     6     5     4     3     2     1     0\r
168           +-----+-----+-----+-----+-----+-----+-----+-----+\r
169           |   unused  | WS  |            unused           |\r
170           +-----+-----+-----+-----+-----+-----+-----+-----+\r
171 \r
172 \r
173 Byte 02 - Timer 1 Data.  If Timer 1 is enabled, the value in this \r
174           register will be incremented until it overflows.  Upon\r
175           overflow, the sound card will signal a TIMER interrupt\r
176           (INT 08) and set bits 7 and 6 in its status byte.  The\r
177           value for this timer is incremented every eighty (80)\r
178           microseconds.\r
179 \r
180 \r
181 Byte 03 - Timer 2 Data.  If Timer 2 is enabled, the value in this \r
182           register will be incremented until it overflows.  Upon\r
183           overflow, the sound card will signal a TIMER interrupt\r
184           (INT 08) and set bits 7 and 5 in its status byte.  The\r
185           value for this timer is incremented every three hundred\r
186           twenty (320) microseconds.\r
187 \r
188 \r
189 Byte 04 - Timer Control Byte\r
190 \r
191         7     6     5     4     3     2     1     0\r
192      +-----+-----+-----+-----+-----+-----+-----+-----+\r
193      | IRQ | T1  | T2  |     unused      | T2  | T1  |\r
194      | RST | MSK | MSK |                 | CTL | CTL |\r
195      +-----+-----+-----+-----+-----+-----+-----+-----+\r
196 \r
197           bit 7 - Resets the flags for timers 1 & 2.  If set,\r
198                   all other bits are ignored.\r
199           bit 6 - Masks Timer 1.  If set, bit 0 is ignored.\r
200           bit 5 - Masks Timer 2.  If set, bit 1 is ignored.\r
201           bit 1 - When clear, Timer 2 does not operate.\r
202                   When set, the value from byte 03 is loaded into\r
203                   Timer 2, and incrementation begins.\r
204           bit 0 - When clear, Timer 1 does not operate.\r
205                   When set, the value from byte 02 is loaded into\r
206                   Timer 1, and incrementation begins.\r
207 \r
208 \r
209 Byte 08 - CSM Mode / Keyboard Split.\r
210 \r
211         7     6     5     4     3     2     1     0\r
212      +-----+-----+-----+-----+-----+-----+-----+-----+\r
213      | CSM | Key |              unused               |\r
214      | sel | Spl |                                   |\r
215      +-----+-----+-----+-----+-----+-----+-----+-----+\r
216      \r
217           bit 7 - When set, selects composite sine-wave speech synthesis\r
218                   mode (all KEY-ON bits must be clear).  When clear,\r
219                   selects FM music mode.\r
220 \r
221           bit 6 - Selects the keyboard split point (in conjunction with\r
222                   the F-Number data).  The documentation in the Sound \r
223                   Blaster manual is utterly incomprehensible on this;\r
224                   I can't reproduce it without violating their copyright.\r
225 \r
226 \r
227 Bytes 20-35 - Amplitude Modulation / Vibrato / Envelope Generator Type /\r
228               Keyboard Scaling Rate / Modulator Frequency Multiple\r
229 \r
230         7     6     5     4     3     2     1     0\r
231      +-----+-----+-----+-----+-----+-----+-----+-----+\r
232      | Amp | Vib | EG  | KSR |  Modulator Frequency  |\r
233      | Mod |     | Typ |     |       Multiple        |\r
234      +-----+-----+-----+-----+-----+-----+-----+-----+\r
235 \r
236           bit 7 - Apply amplitude modulation when set; AM depth is\r
237                   controlled by the AM-Depth flag in address BD.\r
238           bit 6 - Apply vibrato when set;  vibrato depth is controlled\r
239                   by the Vib-Depth flag in address BD.\r
240           bit 5 - When set, the sustain level of the voice is maintained\r
241                   until released; when clear, the sound begins to decay\r
242                   immediately after hitting the SUSTAIN phase.\r
243           bit 4 - Keyboard scaling rate.  This is another incomprehensible\r
244                   bit in the Sound Blaster manual.  From experience, if \r
245                   this bit is set, the sound's envelope is foreshortened as\r
246                   it rises in pitch.\r
247           bits 3-0 - These bits indicate which harmonic the operator will \r
248                   produce sound (or modulation) in relation to the voice's \r
249                   specified frequency:\r
250 \r
251                       0 - one octave below\r
252                       1 - at the voice's specified frequency\r
253                       2 - one octave above\r
254                       3 - an octave and a fifth above\r
255                       4 - two octaves above\r
256                       5 - two octaves and a major third above\r
257                       6 - two octaves and a fifth above\r
258                       7 - two octaves and a minor seventh above\r
259                       8 - three octaves above\r
260                       9 - three octaves and a major second above\r
261                       A - three octaves and a major third above\r
262                       B -  "       "     "  "   "     "     "\r
263                       C - three octaves and a fifth above\r
264                       D -   "      "     "  "   "     "\r
265                       E - three octaves and a major seventh above\r
266                       F -   "      "     "  "   "      "      "\r
267                   \r
268 \r
269 Bytes 40-55 - Level Key Scaling / Total Level\r
270 \r
271         7     6     5     4     3     2     1     0\r
272      +-----+-----+-----+-----+-----+-----+-----+-----+\r
273      |  Scaling  |             Total Level           |\r
274      |   Level   | 24    12     6     3    1.5   .75 | <-- dB\r
275      +-----+-----+-----+-----+-----+-----+-----+-----+\r
276 \r
277           bits 7-6 - causes output levels to decrease as the frequency\r
278                      rises:\r
279 \r
280                           00   -  no change\r
281                           10   -  1.5 dB/8ve\r
282                           01   -  3 dB/8ve\r
283                           11   -  6 dB/8ve\r
284 \r
285           bits 5-0 - controls the total output level of the operator.\r
286                      all bits CLEAR is loudest; all bits SET is the\r
287                      softest.  Don't ask me why.\r
288 \r
289 \r
290 Bytes 60-75 - Attack Rate / Decay Rate\r
291 \r
292         7     6     5     4     3     2     1     0\r
293      +-----+-----+-----+-----+-----+-----+-----+-----+\r
294      |         Attack        |          Decay        |\r
295      |          Rate         |          Rate         |\r
296      +-----+-----+-----+-----+-----+-----+-----+-----+\r
297 \r
298           bits 7-4 - Attack rate.  0 is the slowest, F is the fastest.\r
299           bits 3-0 - Decay rate.  0 is the slowest, F is the fastest.\r
300 \r
301 \r
302 Bytes 80-95 - Sustain Level / Release Rate\r
303 \r
304         7     6     5     4     3     2     1     0\r
305      +-----+-----+-----+-----+-----+-----+-----+-----+\r
306      |     Sustain Level     |         Release       |\r
307      | 24    12     6     3  |          Rate         |\r
308      +-----+-----+-----+-----+-----+-----+-----+-----+\r
309 \r
310           bits 7-4 - Sustain Level.  0 is the loudest, F is the softest.\r
311           bits 3-0 - Release Rate.  0 is the slowest, F is the fastest.\r
312 \r
313 \r
314 Bytes A0-B8 - Octave / F-Number / Key-On\r
315 \r
316         7     6     5     4     3     2     1     0\r
317      +-----+-----+-----+-----+-----+-----+-----+-----+\r
318      |        F-Number (least significant byte)      |  (A0-A8)\r
319      |                                               |\r
320      +-----+-----+-----+-----+-----+-----+-----+-----+\r
321 \r
322         7     6     5     4     3     2     1     0\r
323      +-----+-----+-----+-----+-----+-----+-----+-----+\r
324      |  Unused   | Key |    Octave       | F-Number  |  (B0-B8)\r
325      |           | On  |                 | most sig. |\r
326      +-----+-----+-----+-----+-----+-----+-----+-----+\r
327 \r
328           bit   5  - Channel is voiced when set, silent when clear.\r
329           bits 4-2 - Octave (0-7).  0 is lowest, 7 is highest.\r
330           bits 1-0 - Most significant bits of F-number.\r
331 \r
332      In octave 4, the F-number values for the chromatic scale and their \r
333      corresponding frequencies would be:\r
334 \r
335         F Number     Frequency     Note\r
336            16B          277.2       C#\r
337            181          293.7       D\r
338            198          311.1       D#\r
339            1B0          329.6       E\r
340            1CA          349.2       F\r
341            1E5          370.0       F#\r
342            202          392.0       G\r
343            220          415.3       G#\r
344            241          440.0       A\r
345            263          466.2       A#\r
346            287          493.9       B\r
347            2AE          523.3       C\r
348 \r
349 \r
350 Bytes C0-C8 - Feedback / Algorithm\r
351 \r
352         7     6     5     4     3     2     1     0\r
353      +-----+-----+-----+-----+-----+-----+-----+-----+\r
354      |         unused        |    Feedback     | Alg |\r
355      |                       |                 |     |\r
356      +-----+-----+-----+-----+-----+-----+-----+-----+\r
357 \r
358           bits 3-1 - Feedback strength.  If all three bits are set to\r
359                      zero, no feedback is present.  With values 1-7,\r
360                      operator 1 will send a portion of its output back\r
361                      into itself.  1 is the least amount of feedback,\r
362                      7 is the most.\r
363           bit 0    - If set to 0, operator 1 modulates operator 2.  In this\r
364                      case, operator 2 is the only one producing sound.\r
365                      If set to 1, both operators produce sound directly.\r
366                      Complex sounds are more easily created if the algorithm\r
367                      is set to 0.\r
368 \r
369 \r
370 Byte BD - Amplitude Modulation Depth / Vibrato Depth / Rhythm\r
371 \r
372         7     6     5     4     3     2     1     0\r
373      +-----+-----+-----+-----+-----+-----+-----+-----+\r
374      | AM  | Vib | Rhy | BD  | SD  | TOM | Top | HH  |\r
375      | Dep | Dep | Ena |     |     |     | Cym |     |\r
376      +-----+-----+-----+-----+-----+-----+-----+-----+\r
377 \r
378           bit 7 - Set:    AM depth is 4.8dB\r
379                   Clear:  AM depth is 1 dB\r
380           bit 6 - Set:    Vibrato depth is 14 cent\r
381                   Clear:  Vibrato depth is 7 cent\r
382           bit 5 - Set:    Rhythm enabled  (6 melodic voices) \r
383                   Clear:  Rhythm disabled (9 melodic voices)\r
384           bit 4 - Bass drum on/off\r
385           bit 3 - Snare drum on/off\r
386           bit 2 - Tom tom on/off\r
387           bit 1 - Cymbal on/off\r
388           bit 0 - Hi Hat on/off\r
389 \r
390           Note:  KEY-ON registers for channels 06, 07, and 08 must be OFF\r
391                  in order to use the rhythm section.  Other parameters\r
392                  such as attack/decay/sustain/release must also be set\r
393                  appropriately.\r
394 \r
395 \r
396 Bytes E0-F5 - Waveform Select\r
397 \r
398         7     6     5     4     3     2     1     0\r
399      +-----+-----+-----+-----+-----+-----+-----+-----+\r
400      |               unused              |  Waveform |\r
401      |                                   |  Select   |\r
402      +-----+-----+-----+-----+-----+-----+-----+-----+\r
403 \r
404           bits 1-0 - When bit 5 of address 01 is set, the output waveform\r
405                      will be distorted according to the waveform indicated\r
406                      by these two bits.  I'll try to diagram them here,\r
407                      but this medium is fairly restrictive.\r
408 \r
409          ___              ___            ___    ___       _      _\r
410         /   \            /   \          /   \  /   \     / |    / |\r
411        /_____\_______   /_____\_____   /_____\/_____\   /__|___/__|___\r
412               \     /\r
413                \___/\r
414 \r
415             00              01               10               11\r
416 \r
417 \r
418 \r
419  |                          Detecting a Sound Card\r
420  |\r
421  |   According to the AdLib manual, the 'official' method of checking for a \r
422  |   sound card is as follows:\r
423  |\r
424  |      1)  Reset both timers by writing 60h to register 4.\r
425  |      2)  Enable the interrupts by writing 80h to register 4.  NOTE: this\r
426  |          must be a separate step from number 1.\r
427  |      3)  Read the status register (port 388h).  Store the result.\r
428  |      4)  Write FFh to register 2 (Timer 1).\r
429  |      5)  Start timer 1 by writing 21h to register 4.\r
430  |      6)  Delay for at least 80 microseconds.\r
431  |      7)  Read the status register (port 388h).  Store the result.\r
432  |      8)  Reset both timers and interrupts (see steps 1 and 2).\r
433  |      9)  Test the stored results of steps 3 and 7 by ANDing them\r
434  |          with E0h.  The result of step 3 should be 00h, and the \r
435  |          result of step 7 should be C0h.  If both are correct, an\r
436  |          AdLib-compatible board is installed in the computer.\r
437  |\r
438  |\r
439  |                              Making a Sound\r
440  | \r
441  |   Many people have asked me, upon reading this document, what the proper\r
442  |   register values should be to make a simple sound.  Well, here they are.\r
443  | \r
444  |   First, clear out all of the registers by setting all of them to zero.\r
445  |   This is the quick-and-dirty method of resetting the sound card, but it\r
446  |   works.  Note that if you wish to use different waveforms, you must then\r
447  |   turn on bit 5 of register 1.  (This reset need be done only once, at the\r
448  |   start of the program, and optionally when the program exits, just to \r
449  |   make sure that your program doesn't leave any notes on when it exits.)\r
450  |\r
451  |   Now, set the following registers to the indicated value:\r
452  |\r
453  |     REGISTER     VALUE     DESCRIPTION\r
454  |        20          01      Set the modulator's multiple to 1\r
455  |        40          10      Set the modulator's level to about 40 dB\r
456  |        60          F0      Modulator attack:  quick;   decay:   long\r
457  |        80          77      Modulator sustain: medium;  release: medium\r
458  |        A0          98      Set voice frequency's LSB (it'll be a D#)\r
459  |        23          01      Set the carrier's multiple to 1\r
460  |        43          00      Set the carrier to maximum volume (about 47 dB)\r
461  |        63          F0      Carrier attack:  quick;   decay:   long\r
462  |        83          77      Carrier sustain: medium;  release: medium\r
463  |        B0          31      Turn the voice on; set the octave and freq MSB\r
464  |\r
465  |   To turn the voice off, set register B0h to 11h (or, in fact, any value \r
466  |   which leaves bit 5 clear).  It's generally preferable, of course, to\r
467  |   induce a delay before doing so.\r
468  |\r
469  |\r
470  |                             Acknowledgements\r
471  |\r
472  |   Thanks are due to the following people:\r
473  |\r
474  |   Ezra M. Dreisbach (ed10+@andrew.cmu.edu), for providing the information\r
475  |     about the recommended port write delay from the AdLib manual, and the\r
476  |     'official' method of detecting an AdLib-compatible sound card.\r
477  |\r
478  |   Nathan Isaac Laredo (gt7080a@prism.gatech.edu), for providing the\r
479  |     port numbers for stereo sound on the Sound Blaster Pro.\r