gameboy sound emulation by blargg

Game Boy Sound Operation
------------------------
Shay Green (blargg)
gblargg@gmail.com
http://www.slack.net/~ant/

** This is an incomplete draft

This documents the behavior of Game Boy sound; details which aren't
relevant to the observable behavior have been omitted unless they
clarify understanding. It is aimed at answering all questions about
exact operation, rather than describing how to use sound effectively in
Game Boy programs. Values in hexadecimal (base 16) are generally written
with a $ prefix. Bits are numbered from 0 to 7, where bit N has a weight
of 2^N. A nybble is 4 bits, half a byte. Obscure behavior is described
separately to increase clarity elsewhere.

Contact me for a set of test ROMs that verify most behavior described
here.


Contents
--------
- Overview
- Registers
- Channels
- Timer
- Frame Sequencer
- Length Counter
- Volume Envelope
- Square Wave
- Frequency Sweep
- Noise Channel
- Wave Channel
- Channel DAC
- Trigger Event
- Mixer
- Power Control
- Register Reading
- Vin Mixing
- Obscure Behavior
- Differences
- To Do
- Thanks


Overview
--------
The Game Boy has four sound channels: two square waves with adjustable
duty, a programmable wave table, and a noise generator. Each has some
kind of frequency (pitch) control. The first square channel also has an
automatic frequency sweep unit to help with sound effects. The squares
and noise each have a volume envelope unit to help with fading notes and
sound effects, while the wave channel has only limited manual volume
control. Each channel has a length counter that can silence the channel
after a preset time, to handle note durations. Each channel can be
individually panned to the far left, center, or far right. The master
volume of the left and right outputs can also be adjusted.

Different versions of the Game Boy sound hardware have slightly
different behavior. The following models have been tested:

	DMG-CPU-03	original Game Boy
	DMG-CPU-05
	DMG-CPU-06
	MGB-LCPU-01	Game Boy Pocket
	CGB-CPU-02	Game Boy Color
	CGB-CPU-04
	CGB-CPU-05


Registers
---------
Sound registers are mapped to $FF10-$FF3F in memory. Each channel has
five logical registers, NRx0-NRx4, though some don't use NRx0. The value
written to bits marked with '-' has no effect. Reference to the value in
a register means the last value written to it.

	Name Addr 7654 3210 Function
	- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
			Square 1
	NR10 FF10 -PPP NSSS	Sweep period, negate, shift
	NR11 FF11 DDLL LLLL	Duty, Length load (64-L)
	NR12 FF12 VVVV APPP	Starting volume, Envelope add mode, period
	NR13 FF13 FFFF FFFF	Frequency LSB
	NR14 FF14 TL-- -FFF	Trigger, Length enable, Frequency MSB

			Square 2
	     FF15 ---- ---- Not used
	NR21 FF16 DDLL LLLL	Duty, Length load (64-L)
	NR22 FF17 VVVV APPP	Starting volume, Envelope add mode, period
	NR23 FF18 FFFF FFFF	Frequency LSB
	NR24 FF19 TL-- -FFF	Trigger, Length enable, Frequency MSB

			Wave
	NR30 FF1A E--- ----	DAC power
	NR31 FF1B LLLL LLLL	Length load (256-L)
	NR32 FF1C -VV- ----	Volume code (00=0%, 01=100%, 10=50%, 11=25%)
	NR33 FF1D FFFF FFFF	Frequency LSB
	NR34 FF1E TL-- -FFF	Trigger, Length enable, Frequency MSB

			Noise
	     FF1F ---- ---- Not used
	NR41 FF20 --LL LLLL	Length load (64-L)
	NR42 FF21 VVVV APPP	Starting volume, Envelope add mode, period
	NR43 FF22 SSSS WDDD	Clock shift, Width mode of LFSR, Divisor code
	NR44 FF23 TL-- ----	Trigger, Length enable

			Control/Status
	NR50 FF24 ALLL BRRR	Vin L enable, Left vol, Vin R enable, Right
vol
	NR51 FF25 NW21 NW21	Left enables, Right enables
	NR52 FF26 P--- NW21	Power control/status, Channel length statuses

			Not used
	     FF27 ---- ----
	     .... ---- ----
	     FF2F ---- ----

			Wave Table
	     FF30 0000 1111	Samples 0 and 1
	     ....
	     FF3F 0000 1111	Samples 30 and 31


Channels
--------
Each channel has a frequency timer which clocks a waveform generator.
The waveform's volume is adjusted and fed to the mixer. The mixer
converts each channel's waveform into an electrical signal and outputs
this to the left and/or right channels. Finally, a master volume control
adjusts the left and right outputs. The channels have the following
units that are connected from left to right:

Square 1: Sweep -> Timer -> Duty -> Length Counter -> Envelope -> Mixer

Square 2:          Timer -> Duty -> Length Counter -> Envelope -> Mixer

Wave:              Timer -> Wave -> Length Counter -> Volume   -> Mixer

Noise:             Timer -> LFSR -> Length Counter -> Envelope -> Mixer

The mixer has a separate DAC for each channel, followed by on/off
controls for left and right outputs. The left/right outputs from each
channel are then added together and fed to the left/right master volume
controls.

In general, all units in the channels are always running. For example,
even if a channel is silent, several units will still be calculating
values even though they aren't used.


Timer
-----
A timer generates an output clock every N input clocks, where N is the
timer's period. If a timer's rate is given as a frequency, its period is
4194304/frequency in Hz. Each timer has an internal counter that is
decremented on each input clock. When the counter becomes zero, it is
reloaded with the period and an output clock is generated.


Frame Sequencer
---------------
The frame sequencer generates low frequency clocks for the modulation
units. It is clocked by a 512 Hz timer.

	Step	Length Ctr	Vol Env		Sweep
	- - - - - - - - - - - - - - - - - - - -
	0		Clock		-			-
	1		-			-			-
	2		Clock		-			Clock
	3		-			-			-
	4		Clock		-			-
	5		-			-			-
	6		Clock		-			Clock
	7		-			Clock		-
	- - - - - - - - - - - - - - - - - - - -
	Rate	256 Hz		64 Hz		128 Hz


Length Counter
--------------
A length counter disables a channel when it decrements to zero. It
contains an internal counter and enabled flag. Writing a byte to NRx1
loads the counter with 64-data (256-data for wave channel). The counter
can be reloaded at any time.

A channel is said to be disabled when the internal enabled flag is
clear. When a channel is disabled, its volume unit receives 0, otherwise
its volume unit receives the output of the waveform generator. Other
units besides the length counter can enable/disable the channel as well.

Each length counter is clocked at 256 Hz by the frame sequencer. When
clocked while enabled by NRx4 and the counter is not zero, it is
decremented. If it becomes zero, the channel is disabled.


Volume Envelope
---------------
A volume envelope has a volume counter and an internal timer clocked at
64 Hz by the frame sequencer. When the timer generates a clock and the
envelope period is not zero, a new volume is calculated by adding or
subtracting (as set by NRx2) one from the current volume. If this new
volume within the 0 to 15 range, the volume is updated, otherwise it is
left unchanged and no further automatic increments/decrements are made
to the volume until the channel is triggered again.

When the waveform input is zero the envelope outputs zero, otherwise it
outputs the current volume.

Writing to NRx2 causes obscure effects on the volume that differ on
different Game Boy models (see obscure behavior).


Square Wave
-----------
A square channel's frequency timer period is set to (2048-frequency)*4.
Four duty cycles are available, each waveform taking 8 frequency timer
clocks to cycle through:

	Duty	Waveform	Ratio
	- - - - - - - - - - - - -
	0		00000001	12.5%
	1		10000001	25%
	2		10000111	50%
	3		01111110	75%


Frequency Sweep
---------------
The first square channel has a frequency sweep unit, controlled by NR10.
This has a timer, internal enabled flag, and frequency shadow register.
It can periodically adjust square 1's frequency up or down.

During a trigger event, several things occur:
- Square 1's frequency is copied to the shadow register.
- The sweep timer is reloaded.
- The internal enabled flag is set if either the sweep period or shift
are non-zero, cleared otherwise.
- If the sweep shift is non-zero, frequency calculation and the overflow
check are performed immediately.

Frequency calculation consists of taking the value in the frequency
shadow register, shifting it right by sweep shift, optionally negating
the value, and summing this with the frequency shadow register to
produce a new frequency. What is done with this new frequency depends on
the context.

The overflow check simply calculates the new frequency and if this is
greater than 2047, square 1 is disabled.

The sweep timer is clocked at 128 Hz by the frame sequencer. When it
generates a clock and the sweep's internal enabled flag is set and the
sweep period is not zero, a new frequency is calculated and the overflow
check is performed. If the new frequency is 2047 or less and the sweep
shift is not zero, this new frequency is written back to the shadow
frequency and square 1's frequency in NR13 and NR14, then frequency
calculation and overflow check are run AGAIN immediately using this new
value, but this second new frequency is not written back.

Square 1's frequency can be modified via NR13 and NR14 while sweep is
active, but the shadow frequency won't be affected so the next time the
sweep updates the channel's frequency this modification will be lost.


Noise Channel
-------------
The noise channel's frequency timer period is set by a base divisor
shifted left some number of bits.

	Divisor code	Divisor
	- - - - - - - - - - - -
		0			  8
		1			 16
		2			 32
		3			 48
		4			 64
		5			 80
		6			 96
		7			112

The linear feedback shift register (LFSR) generates a pseudo-random bit
sequence. It has a 15-bit shift register with feedback. When clocked by
the frequency timer, the low two bits (0 and 1) are XORed, all bits are
shifted right by one, and the result of the XOR is put into the
now-empty high bit. If width mode is 1 (NR43), the XOR result is ALSO
put into bit 6 AFTER the shift, resulting in a 7-bit LFSR. The waveform
output is bit 0 of the LFSR, INVERTED.


Wave Channel
------------
The wave channel plays a 32-entry wave table made up of 4-bit samples.
Each byte encodes two samples, the first in the high bits. The wave
channel has a sample buffer and position counter.

The wave channel's frequency timer period is set to (2048-frequency)*2.
When the timer generates a clock, the position counter is advanced one
sample in the wave table, looping back to the beginning when it goes
past the end, then a sample is read into the sample buffer from this NEW
position.

The DAC receives the current value from the upper/lower nybble of the
sample buffer, shifted right by the volume control.

	Code	Shift	Volume
	- - - - - - - - - - - -
	0		4		  0% (silent)
	1		0		100%
	2		1		 50%
	3		2		 25%

Wave RAM can only be properly accessed when the channel is disabled (see
obscure behavior).


Trigger Event
-------------
Writing a value to NRx4 with bit 7 set causes the following things to
occur:

- Channel is enabled (see length counter).
- If length counter is zero, it is set to 64 (256 for wave channel).
- Frequency timer is reloaded with period.
- Volume envelope timer is reloaded with period.
- Channel volume is reloaded from NRx2.
- Noise channel's LFSR bits are all set to 1.
- Wave channel's position is set to 0 but sample buffer is NOT refilled.
- Square 1's sweep does several things (see frequency sweep).

Note that if the channel's DAC is off, after the above actions occur the
channel will be immediately disabled again.


Channel DAC
-----------
Each channel has a 4-bit digital-to-analog convertor (DAC). This
converts the input value to a proportional output voltage. An input of 0
generates -1.0 and an input of 15 generates +1.0, using arbitrary
voltage units.

DAC power is controlled by the upper 5 bits of NRx2 (top bit of NR30 for
wave channel). If these bits are not all clear, the DAC is on, otherwise
it's off and outputs 0 volts. Also, any time the DAC is off the channel
is kept disabled (but turning the DAC back on does NOT enable the
channel).


Mixer
-----
Each channel's DAC output goes to a pair of on/off switches for the left
and right channels before they are sent to the left/right mixers. A
mixer simply adds the voltages from each channel together. These
left/right switches are controlled by NR51. When a switch is off, the
mixer receives 0 volts.

The Vin bits of NR50 control mixing of the Vin signal from the
cartridge, allowing extra sound hardware.

The mixed left/right signals go to the left/right master volume
controls. These multiply the signal by (volume+1). The volume step
relative to the channel DAC is such that a single channel enabled via
NR51 playing at volume of 2 with a master volume of 7 is about as loud
as that channel playing at volume 15 with a master volume of 0.


Power Control
-------------
NR52 controls power to the sound hardware. When powered off, all
registers (NR10-NR51) are instantly written with zero and any writes to
those registers are ignored while power remains off (except on the DMG,
where length counters are unaffected by power and can still be written
while off). When powered on, the frame sequencer is reset so that the
next step will be 0, the square duty units are reset to the first step
of the waveform, and the wave channel's sample buffer is reset to 0.

Power state does not affect wave memory, which can always be
read/written. It also does not affect the 512 Hz timer that feeds the
frame sequencer.

When the Game Boy is switched on (before the internal boot ROM
executes), the values in the wave table depend on the model. On the DMG,
they are somewhat random, though the particular pattern is generally the
same for each individual Game Boy unit. The game R-Type doesn't
initialize wave RAM and thus relies on these. One set of values is

	84 40 43 AA 2D 78 92 3C 60 59 59 B0 34 B8 2E DA

On the Game Boy Color, the values are consistently

	00 FF 00 FF 00 FF 00 FF 00 FF 00 FF 00 FF 00 FF


Register Reading
----------------
Reading NR52 yields the current power status and each channel's enabled
status (from the length counter).

Wave RAM reads back as the last value written.

When an NRxx register is read back, the last written value ORed with the
following is returned:

		  NRx0 NRx1 NRx2 NRx3 NRx4
		 - - - - - - - - - - - - - -
	NR1x  $80  $3F  $00  $FF  $BF
	NR2x  $FF  $3F  $00  $FF  $BF
	NR3x  $7F  $FF  $9F  $FF  $BF
	NR4x  $FF  $FF  $00  $00  $BF
	NR5x  $00  $00  $70

	$FF27-$FF2F always read back as $FF

That is, the channel length counters, frequencies, and unused bits
always read back as set to all 1s.


Vin Mixing
----------
The cartridge connector includes a sound input called Vin. When enabled
via NR50, it is mixed in before the master volume controls. On the DMG
and MGB, 0.847 volts gives equivalent to 0 on a channel DAC, and 3.710
volts is equivalent to 15 on a DAC, with other values linearly
distributed between those voltages. On the CGB, the range is 1.920 volts
to 2.740 volts, a quarter of the DMG range, thus sound fed to the CGB's
Vin is significantly louder.


Obscure Behavior
----------------
- The volume envelope and sweep timers treat a period of 0 as 8.

- Just after powering on, the first duty step of the square waves after
they are triggered for the first time is played as if it were 0. Also,
the square duty sequence clocking is disabled until the first trigger.

- When triggering the wave channel, the first sample to play is the
previous one still in the high nybble of the sample buffer, and the next
sample is the second nybble from the wave table. This is because it
doesn't load the first byte on trigger like it "should". The first
nybble from the wave table is thus not played until the waveform loops.

- When triggering a square channel, the low two bits of the frequency
timer are NOT modified.

- Extra length clocking occurs when writing to NRx4 when the frame
sequencer's next step is one that doesn't clock the length counter. In
this case, if the length counter was PREVIOUSLY disabled and now enabled
and the length counter is not zero, it is decremented. If this decrement
makes it zero and trigger is clear, the channel is disabled. On the
CGB-02, the length counter only has to have been disabled before; the
current length enable state doesn't matter. This breaks at least one
game (Prehistorik Man), and was fixed on CGB-04 and CGB-05.

- If a channel is triggered when the frame sequencer's next step is one
that doesn't clock the length counter and the length counter is now
enabled and length is being set to 64 (256 for wave channel) because it
was previously zero, it is set to 63 instead (255 for wave channel).

- If a channel is triggered when the frame sequencer's next step will
clock the volume envelope, the envelope's timer is reloaded with one
greater than it would have been.

- Using a noise channel clock shift of 14 or 15 results in the LFSR
receiving no clocks.

- Clearing the sweep negate mode bit in NR10 after at least one sweep
calculation has been made using the negate mode since the last trigger
causes the channel to be immediately disabled. This prevents you from
having the sweep lower the frequency then raise the frequency without a
trigger inbetween.

- If the wave channel is enabled, accessing any byte from $FF30-$FF3F is
equivalent to accessing the current byte selected by the waveform
position. Further, on the DMG accesses will only work in this manner if
made within a couple of clocks of the wave channel accessing wave RAM;
if made at any other time, reads return $FF and writes have no effect.

- Triggering the wave channel on the DMG while it reads a sample byte
will alter the first four bytes of wave RAM. If the channel was reading
one of the first four bytes, only the first byte will be rewritten with
the byte being read. If the channel was reading one of the later 12
bytes, the first FOUR bytes of wave RAM will be rewritten with the four
aligned bytes that the read was from (bytes 4-7, 8-11, or 12-15); for
example if it were reading byte 9 when it was retriggered, the first
four bytes would be rewritten with the contents of bytes 8-11. To avoid
this corruption you should stop the wave by writing 0 then $80 to NR30
before triggering it again. The game Duck Tales encounters this issue
part way through most songs.

- "Zombie" mode: the volume can be manually altered while a channel is
playing by writing to NRx2. Behavior depends on the old and new values
of NRx2, and whether the envlope has stopped automatic updates. The
CGB-02 and CGB-04 are the most consistent:

	- If the old envelope period was zero and the envelope is still
doing automatic updates, volume is incremented by 1, otherwise if the
envelope was in subtract mode, volume is incremented by 2.
	- If the mode was changed (add to subtract or subtract to add),
volume is set to 16-volume.
	- Only the low 4 bits of volume are kept after the above operations.

Other models behave differently, especially the DMG units which have
crazy behavior in some cases. The only useful consistent behavior is
using add mode with a period of zero in order to increment the volume by
1. That is, write $V8 to NRx2 to set the initial volume to V before
triggering the channel, then write $08 to NRx2 to increment the volume
as the sound plays (repeat 15 times to decrement the volume by 1). This
allows manual volume control on all units tested.

- When all four channel DACs are off, the master volume units are
disconnected from the sound output and the output level becomes 0. When
any channel DAC is on, a high-pass filter capacitor is connected which
slowly removes any DC component from the signal. The following code
applied at 4194304 Hz implements these two behaviors for one of the DMG
output channels (unoptimized floating point for clarity):

	static double capacitor = 0.0;

	double high_pass( double in, bool dacs_enabled )
	{
		double out = 0.0;
		if ( dacs_enabled )
		{
			out = in - capacitor;

			// capacitor slowly charges to 'in' via their difference
			capacitor = in - out * 0.999958; // use 0.998943 for MGB&CGB
		}
		return out;
	}

The charge factor can be calculated for any output sampling rate as
0.999958^(4194304/rate). So if you were applying high_pass() at 44100
Hz, you'd use a charge factor of 0.996.


Differences
-----------
This summarizes differences I've found among the models tested.

Wave RAM access:
- Possible only when it's doing wave RAM read (DMG-03, DMG-05, DMG-06,
MGB-01).
- Can be accessed any time (CGB-02, CGB-04, CGB-05).

Wave channel re-trigger without disabling first (via NR30):
- Re-writes first four bytes of wave RAM (DMG-03, DMG-05, DMG-06,
MGB-01).
- Behaves normally (CGB-02, CGB-04, CGB-05).

Length counters and power off:
- Preserved and can be written while off (DMG-03, DMG-05, DMG-06,
MGB-01).
- Always zero at power on (CGB-02, CGB-04, CGB-05).

Length clocking on NRx4:
- New length enable doesn't matter (CGB-02).
- Length must now be enabled (DMG-03, DMG-05, DMG-06, CGB-04, CGB-05,
MGB-01).

Volume changes on NRx2 write:
- $x0 to $xx and $x7 to $xx are very screwey (DMG-03, DMG-05, DMG-06,
MGB-01).
- Behavior as described in obscure behavior (CGB-02, CGB-04).
- If mode isn't being changed, only $x8 to $xx affects volume. Mode
change is also a bit different (CGB-05).


To Do
-----
- Using an envelope or sweep period of 0 then switching to another
period also causes an extra clock in some cases.

- Frequency sweep has some really intricate behavior when rewriting
sweep register

- Noise's frequency timer is more complex than described, resulting in
trigger doing something more than simply reloading it. It may have
multiple dividers to achieve the documented periods, with only some of
them being reset on trigger.

- Behavior when triggering and writing to registers within a few clocks
of frame sequencer events has yet to be determined. There will be lots
of odd things uncovered for sure.

- Figure out exactly how noise LFSR is implemented with regard to mode
changes.

- Document exact timing for DMG wave issues.


Thanks
------
- Lord Nightmare for GBSOUND.txt, assistance, testing, GBs to test.
- Laguna for the gnuboy emulator.
- Ville Helin for WLA DX GB-Z80 assembler.
- sinamas for feedback about this document and my test ROMs.

--
Shay Green <gblargg@gmail.com>