Home Memoirs of a Gamer Movies I watched Guidebook Links

the Lobdegg's Comprehensive Guidebook to DOS Programming

Chapter 4 - Audio

Section 4: Ad Lib / OPL2 & OPL3

Introduction

The Ad Lib sound card and subsequent derivatives are quite the step up from a simple square wave generator like the PC Speaker, and even the Tandy 3 Voice sound chip. First released with the Yamaha YM3812 chip in 1987, referred to as OPL2, it set down a fairly complex and robust 9 channel FM synthesizer standard that would be followed for some time throughout the late 80s and the 90s. In 1992, Ad Lib would follow up it's success with the Yamaha YMF262, referred to as OPL3, which expanded the standard from 9 channels to 18, and expanded from 4 sine based waveforms to 8 sine and non-sine based waveforms. Don't worry if you don't know what any of that means in any real sense, because that's exactly what this section aims to make clear.

Note: Channels will be numbered 0-17 through out this section.

The Ad Lib sound card is programmed by sending data, 8 bits at a time, to registers stored inside the Yamaha chips by first writing the register's index to the Index port (0x388), then writing the desired value to the Data port (0x389). Status information can also be retrieved from the Yamaha chips by reading from the Index port (0x388), during which the port is usually referred to as the Status port. Unlike MIDI or Sound Blaster, the IO addresses are thankfully fixed for most normal Ad Lib compatible devices. There is an exception in the modern era to this in the form of the OPL2LPT and OPL3LPT devices by Serdashop, and this will be discussed more later in this section.

    mov al, 0x01
    mov dx, 0x388
    out dx, al
    mov al, 0x20
    mov dx, 0x389
    out dx, al

The original OPL2 specification used almost the entirety of the 8 bit index address space, so when OPL3 was laid out, the decision was made to duplicate the index address space and use 4 IO addresses instead of 2. This takes the shape of a second Index port (0x38A) and a second Data port (0x38B). Following the trend I've often seen, this section will refer to OPL3's index space as 0x100 to 0x1FF. So understand when this text says "Write 1, to register 0x105 to activate OPL3 functionality", what is meant is that index 5 is written to 0x38A followed by a 1 to 0x38B. Many of the OPL2 registers are reflected in the OPL3's secondary index address space. If this sounds a bit wonky, don't worry, it will become clear when we start going over writing to channel and operator registers.

    mov al, 0x05
    mov dx, 0x38A
    out dx, al
    mov al, 0x01
    mov dx, 0x38B
    out dx, al

opl_write:
    push bp
    mov bp, sp
    push ax
    push dx
    mov ax, [bp+4]
    cmp ax, 0x100
    jge .opl3
    mov dx, 0x388
    out dx, al
    mov ax, [bp+6]
    mov dx, 0x389
    out dx, al
    jmp .done
.opl3:
    mov dx, 0x388
    out dx, al
    mov ax, [bp+6]
    mov dx, 0x389
    out dx, al
.done:
    pop dx
    pop ax
    mov sp, bp
    pop bp
    ret

void opl_write(short i, char v) {
  if (i < 0x100) {
    outport(0x388,i);
    outport(0x389,v);
  } else {
    outport(0x38A,i);
    outport(0x38B,v);
  }
}

void opl_write(short i, char v) {
  if (i < 0x100) {
    outp(0x388,0x01);
    outp(0x389,0x20);
  } else {
    outp(0x38A,0x01);
    outp(0x38B,0x20);
  }
}

Initialization

1. Reset both timers by writing 0x60 to index 0x04
2. Set IRQReset by writing 0x80 to 0x04
3. Read the Status port and save the result
4. Write 0xFF to Timer 1 at index 0x02
5. Delay for at least 80 microseconds
6. Start Timer 1 by writing 0x21 to 0x04
7. Read the Status port and save the result
8. Reset both timers by writing 0x60 to index 0x04
9. Set IRQReset by writing 0x80 to 0x04
10. Bitwise AND both saved results by 0xE0. The first should result in 0x00, and the second should result in 0xC0. If both are true, OPL2 detected!

Note: For steps 1 & 2 keep in mind that when IRQReset is set, all other bits are ignored!

    xor ax, ax
    mov [opl2], al

    push 0x60
    push 0x04
    call opl_write
    add sp, 4

    push 0x80
    push 0x04
    call opl_write
    add sp, 4

    mov dx,0x388
    in al, dx
    and al, 0xE0
    mov [s1], al

    push 0xFF
    push 0x01
    call opl_write
    add sp, 4

    ;TODO add 80ms delay

    push 0x21
    push 0x04
    call opl_write
    add sp, 4

    mov dx,0x388
    in al, dx
    and al, 0xE0
    mov [s2], al

    push 0x60
    push 0x04
    call opl_write
    add sp, 4

    push 0x80
    push 0x04
    call opl_write
    add sp, 4

    cmp byte [s1], 0
    jne .done
    cmp byte [s2], 0xC0
    jne .done
    
    inc [opl2]
.done:

    xor ax, ax
    mov [opl3], al
    mov dx, 0x388
    in al, dx
    and al, 0x06
    jnz .postopl3
    
    push 0x01
    push 0x105
    call opl_write
    add sp, 4
    
    inc [opl3]
.postopl3:

opl3 = 0;
if ((inport(0x388) & 0x06)==0) {
  opl_write(0x105,0x01);
  opl3 = 1;
}

opl3 = 0;
if ((inp(0x388) & 0x06)==0) {
  opl_write(0x105,0x01);
  opl3 = 1;
}

Making Noise

1. set the Attack / Decay register for a channel's operators
2. set the channel's F-Number first via the channel's associated #A0 register.
3. set the upper 2 bits of the F-Number, the octave, and set the Note On flag (= 1).

    ;set op1 to 75
    ;that's Attack of 7 and a Decay of 5
    push 0x75
    push 0x68
    call opl_write
    add sp, 4

    ;same again with op2
    push 0x75
    push 0x6B
    call opl_write
    add sp, 4

    ;set the lower 8 bits of the F-Number.
    ;F-Number for an F in octave 4 is 0x1CA
    push 0xCA
    push 0xA3
    call opl_write
    add sp, 4

    ;Set the top 2 bits of the F-Number,
    ;the octave to 4,
    ;and turn the note on by oring 0x20!
    push (0x20|(4<<2)|0x01)
    push 0xB3
    call opl_write
    add sp, 4

;Although we're telling the note to
    ;turn off we still want the octave
    ;and F-Number to remain intact!
    ;Failing to do so will create weird
    ;Sound effects.
    push ((4<<2)|0x01)
    push 0xB3
    call opl_write
    add sp, 4

    ;The Left playback bit is bit 4
    ;which makes 0x10 in hex.
    push 0x10
    push 0xC3
    call opl_write
    add sp, 4

    ;Let's play that F-4 again.
    push 0xCA
    push 0xA3
    call opl_write
    add sp, 4

    push (0x20|(4<<2)|0x01)
    push 0xB3
    call opl_write
    add sp, 4

Clean up

    ;Cycle through all registers
    ;and set them to 0!
    mov cx, 1
    xor ax, ax
    push ax
.clean_loop:
    push cx
    call opl_write
    add sp, 2

    ;Don't forget the OPL3 registers!
    or cx, 0x100
    push cx
    call opl_write
    xor cx, 0x100
    add sp, 2

    inc cx
    cmp cx, 0xF5
    jle .clean_loop
    add sp, 2

\\Cycle through all registers
\\and set them to 0!
int c;
for (c = 0x01; c <= 0xF5; c++) {
  opl_write(c,0);
  \\Don't forget the OPL3 registers!
  opl_write(0x100|c,0);
}

Register Table

For the sake of clarity of function we will be breaking down registers into 3 categories:

1. Global - configures chip wide features
2. Channel - configures channel specific qualities
3. Operator - configures a specific operator

table adapted from OPL3 Programmer's Guide

# - The first digit is either a 0 or a 1 depending on whether the lower 9 channels are targetted, or the higher 9 channels.

* Indices 104 and 105 are OPL3 only!

Global Registers

Channel Registers

Note: Channels 9 through 17 are only available on OPL3

Note: This assumes all channels that support 4 Operator pairs are set to 4 Operator Mode

Operator Registers

Index #20-#35

Index	D7	D6	D5	D4	D3	D2	D1	D0
#20-#35	Tremolo	Vibrato	Sustain	KSR	Frequency Multiplication Factor

Tremolo

If set, the amplitude will be modulated according to the associated flag in the BD register.

Vibrato

If set, the pitch will oscillate slightly according to the associated flag in the BD register.

Sustain

If set, the output level of the register will hold at the Sustain setting written to the associated #80-#95 register for this operator. If clear the note will decay until silent regardless of whether a note off state has been set in the associated channel's #B0-#B8 register.

KSR - Keyboard Scaling Rate

If set, higher pitched notes will pass through their ADSR states faster.

Frequency Multiplication Factor

Adjusts the note given by the associated channel's #A0-#A8 and #B0-#B8 registers by a defined amount according to the following table:

• 0 - one octave below
• 1 - at the voice's specified frequency
• 2 - one octave above
• 3 - an octave and a fifth above
• 4 - two octaves above
• 5 - two octaves and a major third above
• 6 - two octaves and a fifth above
• 7 - two octaves and a minor seventh above
• 8 - three octaves above
• 9 - three octaves and a major second above
• A - three octaves and a major third above
• B - three octaves and a major third above
• C - three octaves and a fifth above
• D - three octaves and a fifth above
• E - three octaves and a major seventh above
• F - three octaves and a major seventh above

Index #40-#45

Index	D7	D6	D5	D4	D3	D2	D1	D0
#40-#55	Key Scale Level		Output Level

Key Scale Level

Applies a varied volume suppression according to the octave value specified to the associated channel's #B0-#B8 register.

• 0 - no change
• 1 - 1.5 dB/octave
• 2 - 3 dB/octave
• 3 - 6 dB/octave

Output Level

The volume suppression applied to this operator. 0 will make the operator output it's maximum volume, 63 will cause near silence.

Index #60-#75

Index	D7	D6	D5	D4	D3	D2	D1	D0
#60-#75	Attack Rate				Decay Rate

Attack Rate

The rate at which the channel will rise from silent to full volume after a note on signal is written to the associated channel's #B0-#B8 register.
0 - slowest, 15 - fastest

Decay Rate

The rate at which the channel will fall after peaking in volume.
0 - slowest, 15 - fastest

Index #80-#95

Index	D7	D6	D5	D4	D3	D2	D1	D0
#80-#95	Sustain Level				Release Rate

Sustain Level

This is the fraction of the full volume level that the note will hold at, provided the Sustain flag for this operator is set in it's associated #20-#35 register.
0 - silent, 15 - loudest

Release Rate

This is the speed at which the note fades in volume after the note off state has been set on the associated channel's #B0-#B8 register.
0 - slowest, 15 - fastest

Index #E0-#F5

Index	D7	D6	D5	D4	D3	D2	D1	D0
#E0-#F5						Waveform Select

Waveform

This specifies the operator's waveform. In OPL2 there are only 4 possible values (0-3), but in OPL3 the options were expanded to 8. They are:

Value	Description	Visual
0	Sine
1	Half Sine
2	Absolute Sine
3	Pulsed Absolute Sine
4	Sine on even periods only
5	Absolute Sine on even periods only
6	Square
7	Derived Square

Infographics shamelessly stolen from OPL3 Programmer's Guide