Retro Isle - Nintendo Game Boy Technical Section

Game Boy Sound

Written by Jonathan Gevaryahu, with help from many, many others.
lord_nightmare at users d0t sourceforge d0t net
I can also be found on Freenode #gnuboy or EFnet #gameboy and #gbdev
(This document is written in the same style/context as Brad Taylor's very
useful NESSOUND.txt; If you found NESSOUND.txt useful for NES work, I hope
you
find this just as useful for Gameboy work)

The latest version of this document can (hopefully) always be obtained from:
http://www.netaxs.com/~gevaryah/GBSOUND.txt
and from Joshua's mirror at:
http://www.joshuawise.com/~nightmare/GBSOUND.txt
and sometime soon, from the devrs.com mirror at:
http://www.devrs.com/gb/files/GBSOUND.txt

All results were obtained by studying prior information available, mainly
the
(in)famous Pan Docs, additional info added to the pan docs by Martin Korth
of
NO$GMB fame, info from some of Jeff Frohwein's various tests, and from
information derived from my own experimentation.
Anything UNVERIFIED is an educated guess based on prior knowledge.

also, as Brad Taylor said so well:
"A special thanks goes out to Matthew Conte, for his expertise on
pseudo-random number generation (amoung other things), which allowed for the
full reverse engineering of the NES's noise channel to take place. Without
his help, I would still be trying to find a needle in a haystack, as far as
the noise's method of pseudo-random number generation goes..."
This applies here as well, since the Gameboy's PRNG is very similar to the
NES'

ANYHOW...

/------------------\
< **Introduction** >
\------------------/

The DMG-CPU/GBC-CPU/SGB-CPU (sometimes referred to as the GB- Z80 due to it's
similarity with the Z80 microprocessor) has, internally, 4 semi-analog sound
channels. These can be output in a conditional (on or off) fashion to one or
both of the Gameboy's output terminals, achieving a pseudo-stereo effect.
The sound sometimes referred to as a PAPU, or Pseudo-Audio-Processing-Unit,
Pseudo because it isn't actually a separate unit. However, from a
programming
standpoint, for all intents and purposes it is a separate circuit from the
main
processor.
I'll go into as deep detail as I can when explaining the inner workings of
this
PAPU.

/---------------------\
< **Channel Details** >
\---------------------/
Each one of the four channels is different in it's own way:

Channel 1 is a Square wave channel with volume envelope and frequency sweep
functions.

Channel 2 is a Square wave channel with volume envelope functions only.

Channel 3 is a programmable wave channel with 32 4-bit programmable samples,
played in sequence.

Channel 4 is a 'white noise' channel with volume envelope functions.

Channels 1-3 can produce frequencies of 64hz-131072hz
Channel 4 can produce bit-frequencies of 2hz-1048576hz.

NOTE:
On the SGB-CPU, due to video sync issues, the processor runs approximately
2.4%
faster than the handheld units, and, respectively, sounds are played at a
2.4%
higher frequency.

/------------------------\
< **Register Addresses** >
\------------------------/

The addresses through which the sound channels can be accessed are:
$Addresses: (Description), (Register shorthand)
$FF10 -- $FF14: Channel 1, Referred to as NR10-NR14
$FF15 is unused, was probably going to be a sweep reg for channel 2
originally
$FF16 -- $FF19: Channel 2, Referred to as NR21-NR24
$FF1A -- $FF1E: Channel 3, Referred to as NR30-NR34
$FF1F is unused, was probably going to be a sweep reg for channel 4
originally
$FF20 -- $FF23: Channel 4, Referred to as NR41-NR44
$FF24 controls the Vin status and volume, Referred to as NR50
$FF25 selects which output each channel goes to, Referred to as NR51
$FF26 is the status register, and also controls the sound circuit's power.
Referred to as NR52
$FF27 -- $FF2F are unused.
$FF30 -- $FF3F is the load register space for the 4-bit samples for channel
3

PARTIALLY VERIFIED: All registers are read/writable except for the
initialize
flags for each channel, and $FF30-$FF3F, which is read/writable, but is
scrambled slightly once channel 3 is played with new data written there.
The low 4 bits of $FF26 have no effect whatsoever if written to, as they are
status flags.

Writing a 0 to bit position 7 in register $FF26(NR52) disables the power to
the
audio processing unit, which can give a 15-20% increase in battery life if
used
properly. see note on power consumption for details.

PARTIALLY VERIFIED: Any writes to any register while the audio processing
unit
is OFF have NO EFFECT WHATSOEVER, with the exception of the $FF30-$FF3F
range.

PARTIALLY VERIFIED: Any writes to any unused bits in any register are
RETAINED
as long as the APU isn't powered off, so they can be theoretically used for
temporary storage by programs. I have yet to see a program which DOES this,
but
it is quite doable!

My writing a test ROM to dump the entire audio range's initial state to SRAM
memory revealed a few mistakes in versions prior to 99.20 of this document,
so
CHECK EVERYTHING AGAIN CAREFULLY!

Each channel has 5 registers associated with it, and, like the NES, they are
in
sets:

/-------\
< Set 1 >
\-------/
Master on/off and Sweep Register

Channel 1 - $FF10(NR10)[sq1]
---------------------------------------------
7 Unused
6-4 Sweep time(update rate) (if 0, sweeping is off)
3 Sweep Direction (1: decrease, 0: increase)
2-0 Sweep RtShift amount (if 0, sweeping is off)

Channel 3 - $FF1A(NR30)[wave]
---------------------------------------------
7 Channel 3 Master on/off
6-0 Unused

Channels 2,4 - $FF15(NR20)[sq2], $FF1F(NR40)[noise]
---------------------------------------------
7-0 Unused

/-------\
< Set 2 >
\-------/
Wave pattern duty and Sound length Register

Channels 1,2,4 - $FF11(NR11)[sq1], $FF16(NR21)[sq2], $FF20(NR41)[noise]
---------------------------------------------
7-6 Wave pattern duty (only on channels 1 and 2)
5-0 Length counter load register

Channel 3 - $FF1B(NR31)[wave]
---------------------------------------------
7-0 Length counter load register

/-------\
< Set 3 >
\-------/
Volume Envelope Control register

Channels 1,2,4 - $FF12(NR12)[sq1], $FF17(NR22)[sq2], $FF21(NR42)[noise]
---------------------------------------------
7-4 (Initial) Channel Volume
3 Volume sweep direction (0: down; 1: up)
2-0 Length of each step in sweep (if 0, sweeping is off)
NOTE: each step is n/64 seconds long, where n is 1-7

Channel 3 - $FF1C(NR32)[wave]
---------------------------------------------
7 Unused
6-5 Volume Level (0: Mute; 1: 100%; 2: 50% [rtshift 1]; 3: 25% [rtshift 2])
4-0 Unused

/-------\
< Set 4 >
\-------/
Frequency LSbs and Noise options

Channels 1,2,3 - $FF13(NR13)[sq1], $FF18(NR23)[sq2], $FF1D(NR33)[wave]
---------------------------------------------
7-0 8 Least Significant bits of frequency (3 MSbs are in set 5)

Channel 4 - $FF22(NR43)[noise]
---------------------------------------------
7-4 Shift clock frequency (s)
3 Shift Register width (0: 15 bits; 1: 7 bits)
2-0 Dividing Ratio of frequency (r)
Frequency = 524288 Hz / r / 2^(s+1) ;For r=0 use r=0.5 instead

/-------\
< Set 5 >
\-------/
Playback flags and frequency MSbs

Channels 1,2,3,4 - $FF14(NR14)[sq1], $FF19(NR24)[sq2], $FF1E(NR34)[wave],
$FF23(NR44)[noise]
---------------------------------------------
7 Initialize (trigger channel start, AKA channel INIT) (Write only)
6 Consecutive select/length counter enable (Read/Write)
5-3 Unused
2-0 3 Most Significant bits of frequency (channels 1,2,3) (Read?/Write)

/-------------\
< Control Set >
\-------------/

$FF24(NR50) - Vin (input line on cart connector) / Main Output Volume
Control
---------------------------------------------
7 Output Vin to Main SO2 output level control (1: on; 0: off)
6-4 SO2 (Left) Main Output level (volume)
3 Output Vin to Main SO1 output level control (1: on; 0: off)
2-0 SO1 (Right) Main Output level (volume)

$FF25(NR51) - Sound Output terminal select (1: enabled; 0: disabled)
---------------------------------------------
7 Channel 4 to Main SO2 output level control (Left)
6 Channel 3 to Main SO2 output level control (Left)
5 Channel 2 to Main SO2 output level control (Left)
4 Channel 1 to Main SO2 output level control (Left)
3 Channel 4 to Main SO1 output level control (Right)
2 Channel 3 to Main SO1 output level control (Right)
1 Channel 2 to Main SO1 output level control (Right)
0 Channel 1 to Main SO1 output level control (Right)

$FF26(NR52) - Master control and status flags
---------------------------------------------
7 Master sound circuitry power control (read/write)
6-4 unused
3 Channel 4 status flag (Read-only)
2 Channel 3 status flag (Read-only)
1 Channel 2 status flag (Read-only)
0 Channel 1 status flag (Read-only)

IMPORTANT NOTE ON POWER CONSUMPTION!!!
Writing a 0 to bit position 7 in register $FF26(NR52) disables the power to
the
audio processing unit, which can give a 15-20% increase in battery life if
used
properly. When the PAPU is disabled, all registers in the range $FF10-$FF2F
are
unreadable and unwritable except for register $FF26(NR52). When the power is
disabled, all register values, hidden or accessible, are lost, except for
both
the hidden internal and regular $FF30-FF3F wave pattern memory area. Reading
from $FF26(NR52) while the audio processing unit is disabled will yield the
values last written into the unused bits (0x70), all other bits are 0.
A good way to use this in your game is to disable the audio unit during any
time where there will be no sound playing for an extended period (when
paused
for instance), or where there will be long gaps between any sounds played.
Note that turning on or off the audio unit results in an audible CLICK noise
over the SOx output lines (AKA the stereo channels). The volume of the click
can be reduced considerably by turning both of the output master volume
controls to zero before turning off the sound core, but practically all
games
don't bother doing this, as the click is almost unnoticable among other
sounds.

/-------------------------\
< Initial Register Values >
\-------------------------/
Upon a sound core power-cycle, the registers will be loaded with the
following
values:
$FF10(NR10) - 0x80
$FF11(NR11) - 0xBF
$FF12(NR12) - 0xF3
$FF13(NR13) - No Change
$FF14(NR14) - 0xBF
$FF15(NR20) - No Change
$FF16(NR21) - 0x3F
$FF17(NR22) - 0x00
$FF18(NR23) - No Change
$FF19(NR24) - 0xBF
$FF1A(NR30) - 0x7F
$FF1B(NR31) - 0xFF
$FF1C(NR32) - 0x9F
$FF1D(NR33) - No Change
$FF1E(NR34) - 0xBF
$FF1F(NR40) - No Change
$FF20(NR41) - 0xFF
$FF21(NR42) - 0x00
$FF22(NR43) - 0x00
$FF23(NR44) - 0xBF
$FF24(NR50) - 0x77
$FF25(NR51) - 0xF3
$FF26(NR52) - SEE BELOW

VERIFIED on DMG, SGB, and CGB: Values marked 'No Change' are reset to 0xFF
upon
a system reset or power-cycle.

On the DMG/GBP/CGB, the value of $FF26(NR52) is 0xF_1_ due to the fact that
channel 1 is on-but-faded-out, due to the two-toned 'Gameboy startup sound'.
On the SGB/SGB2, however, there IS no internally-created startup noise, and
so
the initial value is 0xF_0_, and channel 1 is off.

For initial values of $FF30-$FF3F, see section 'Wave pattern memory' below.

/--------------------------\
< **Channel Architecture** >
\--------------------------/
Here, I will try to describe the inner workings of the channels in as much
detail as I can manage. Please note that a few of the points are not
completely
tested and/or understood (particularly the zombie state increment stuff, see
'volume/envelope control unit')

IMPORTANT NOTE!: Lacking an oscilloscope, I'm making a LOT of guesses about
the
specifics (counters, etc), somewhat based on the fact that the NES and
Gameboy
sound units are very very similar, and somewhat by experimental results.
I can pretty much promise that by version 1.0 of this doc, if I ever get
that
far, I will have 100% completely verified info.

Device Square1 Square2 Waveform Noise
------ ------- ------- -------- -----
programmable timer X X X
configurable timer X
length counter X X X X
unified length clock <<COMMON FOR ALL CHANNELS>>
4-bit DAC X X X X
volume/envelope control unit X X X
master output control switch * * X *
frequency sweep unit X
duty cycle generator X X
PseudoRandom Number Generator X
wave pattern memory X
wave pattern playback/volume shift unit X
SO1/SO2 Control unit * * * *

/--------------------\
< Programmable timer >
\--------------------/
The programmable timer is an 11-bit presettable down counter, with
reloading-
upon-0. It is found in the two squarewave channels and the voluntary wave
channel. Some permutation of it may exist on the noise channel also, but for
all intents and purposes it doesn't exist there.

Channels 1,2,3 - $FF13(NR13)[sq1], $FF18(NR23)[sq2], $FF1D(NR33)[wave]
---------------------------------------------
7-0 8 Least Significant bits of frequency, bits 7-0

Channels 1,2,3 - $FF14(NR14)[sq1], $FF19(NR24)[sq2], $FF1E(NR34)[wave]
---------------------------------------------
2-0 3 Most Significant bits of frequency, bits A-8

The 11-bit frequency value, upon either part being written, is
binary-inverted
(NOT), and the resulting number plus one is placed into the 11-bit counter.
Another possibility is that the 11-bit frequency is subtracted from 2048,
the
result being written into the counter. (either way, the result is the same)

Attempting to read the contents of these registers will yield a null result
(either all 0's or all 1's, I haven't checked yet)

The counter has 'syncronous reloading upon terminal count', meaning that it
will count for N clock cycles before arriving at 0 (the 'terminal count', at
which the counter's TC line is raised), and then be reloaded, taking an
additional cycle, and resume counting). This counter is clocked by the
output
of a 5-bit count-0-to-31-and-loop timer/divider, which itself is clocked by
the
gameboy's standard CPU clock input, 4.194304mhz.
[the pitch doesn't double when in the CGB's doublespeed mode, because
doublespeed mode only makes the *processor* clock on both the rising and
falling edges of the clock signal, which stays constant at 4.194304mhz.]

This makes the output frequency work like this as compared to the 11-bit
freq:

Hz = 4194304 / ((2048 - (11-bit-freq)) << 5)
which could also be written like:
Hz = 4194304 / ((~11-bit-freq + 1) << 5)
or also like:
Hz = 131072 / (~11-bit-freq + 1)

The Terminal Count line is also connected to either the duty cycle
generator,
the wave pattern playback unit, or the pseudorandom number generator's
trigger,
depending on the channel.

NOTE: Channel 1's sweep unit will scramble its counter's contents during a
sweep, and will necessitate a fresh write of the frequency values. (see
sweep
unit)

/--------------------\
< Configurable Timer >
\--------------------/
The configurable timer is the noise channel (channel 4)'s equivalent of a
programmable frequency timer. It is controlled by register $FF22(NR43), and
consists of a customized 3-bit down counter, a 16-bit long down counter with
reload-on-0 and only 1 initially-settable bit. The 3-bit down counter's
initial/reload setting is determined by the setting of the frequency divide
ratio.

Channel 4 - $FF22(NR43)[noise]
---------------------------------------------
2-0 Frequency divide ratio

The down counter is clocked at 2097152 hz, divided from the processor's
4.194304Mhz frequency. The counter counts down until 0, and spends 1 clock
cycle reloading the initial value from the freq divide ratio. When it
reloads,
it inverts the status of its output line.

clock freq: \\\\\\\\\\\\\\\\\\\\\\\\\\\\ 2097152 hz
ratio of: 0 _-_-_-_-_-_-_-_-_-_-_-_-_-_- 1048576 hz
1 __--__--__--__--__--__--__-- 524288 hz
2 ___---___---___---___---___- ~370727.6 hz
3 ____----____----____----____ 262144 hz
4 _____-----_____-----_____--- ~220435.95 hz
5 ______------______------____ ~185363.8 hz
6 _______-------_______------- ~155871.75 hz
7 ________--------________---- 131072 hz

The terminal count/output of the counter is the clock input to the shift
clock.

The shift clock is a 16-bit long down counter which can have any single bit
in
it set as the initial/reload value, the position of that bit being read from
the shift clock frequency register.
UNVERIFIED: Reloading of the value is instantaneous.

Channel 4 - $FF22(NR43)[noise]
---------------------------------------------
7-4 Shift clock frequency

The terminal count of the shift clock is the input clock signal of the
Pseudo-Random Number Generator.

PRNG Frequency = (1048576 Hz / (ratio + 1)) / (2 ^ (shiftclockfreq + 1))
(by '^' I mean 'raised to the power of', NOT 'XOR')

/----------------\
< Length Counter >
\----------------/
The Gameboy's audio channels each feature a length counter, a conditionally
clocked down counter. There are two types of length counters used in the
Gameboy's PAPU: the 5-bit ones used on channels 1, 2, and 4, and the 8-bit
one
used on channel 3. The clock source for each counter is described below.

Values can be loaded into the length counters for each channel using the
following registers:

Channels 1,2,4 - $FF11(NR11)[sq1], $FF16(NR21)[sq2], $FF20(NR41)[noise]
---------------------------------------------
5-0 Length counter load register

The 5-bit value is binary-inverted (NOT) upon a register write, 1 is added
to
the result, and the resulting value is written to the counter. Another
possibility is that the 5-bit length value is subtracted from 64, the result
being written to the counter. (either way, the result is the same)

These length counters are clocked at a rate of 1 count every 1/256th of a
second, taken directly from the unified length clock (256hz, see below).
Therefore: length in seconds = (64 - [length]) * (1/256)

NOTE: In versions of this document prior to 99.18, I had the length counter
clock for channels 1,2,4 being clocked once every 1/64th of a second.
Subsequent testing proved that this was incorrect. Thanks to beware for
asking
me to check it.

Channel 3 - $FF1B(NR31)[wave]
---------------------------------------------
7-0 Length counter load register

The 8-bit value is binary-inverted (NOT) upon a register write, 1 is added
to
the result, and the resulting value is written to the counter. Another
possibility is that the 8-bit length value is subtracted from 256, the
result
being written to the counter. (either way, the result is the same)

This length counter is also clocked at a rate of 1 count every 1/256th of a
second, taken directly from the unified length clock (256hz, see below).
Therefore: length in seconds = (256 - [length]) * (1/256)

Writing a value to a length counter will IMMEDIATELY start the counter
counting
down, regardless of the channel's current on/off state! This will happen ANY
time that the length counter enable bit is on during a write. Several games,
notably 'Mega Man 2' and 'Balloon Kid' prove this.

NOTE: The length counters are NEVER reloaded to their last written value!
They
must be reloaded by hand EVERY TIME, as the values written are destroyed
during
the countdown itself! However, Initializing the channel (setting bit 7 of
$FF14, $FF19, $FF1E, $FF23) when the counter is already at zero will cause a
maximum-length-possible-for-the-channel playback! Be careful!

VERIFIED: If the counter is written to while the length counter enable bit
(see
below) is OFF, the value will remain intact until the enable bit is turned
on.
This is regardless of whether the channel is INITed then, although I'm
fairly
sure it was intended that one would start the counter and the channel during
the same PAPU write.

The clocking of the counter is enabled or disabled depending on the status
of
the 'length counter enable register' (AKA the 'consecutive' bit) in register
set 5, a 1 enabling the counter, a 0 disabling it.

Channels 1,2,3,4 - $FF14(NR14)[sq1], $FF19(NR24)[sq2], $FF1E(NR34)[wave],
$FF23(NR44)[noise]
---------------------------------------------
6 Consecutive select/length counter enable (Read/Write)

The real-time status for the length counter of a given channel can be
attained
by reading register $FF26(NR52). a 1 indicates that the length counter is
non-0, or that the consecutive/length counter enable bit is 0; 0 indicates
that
the length counter is 0, and subsequently that channel is off.

$FF26(NR52) - Master control and status flags
---------------------------------------------
3 Channel 4 status flag (Read-only)
2 Channel 3 status flag (Read-only)
1 Channel 2 status flag (Read-only)
0 Channel 1 status flag (Read-only)

/----------------------\
< Unified Length Clock >
\----------------------/
This is a recent discovery, pointed out to me by beware(of bgb fame). It is
a
single clock, running at 256hz, probably divided directly from the GB
processor's clock (4.194304Mhz). It is used to clock the length counters of
each channel, when the length counter enable bit (see above) for that
particular channel is on. It is common to all channels, so when it clocks
for
one channel it clocks all of them.

UNVERIFIED: It may also be used, after being divided by 2, to clock the
128hz
sweep clock. The last test I did was inconclusive, probably due to some
mistake
I made during testing.

/-----------\
< 4-bit DAC >
\-----------/
This is a plain-old vanilla linear 4-bit DAC, 16 steps of output voltage.
All
of the sound channels use them for output.

/--------------------------------\
< Volume / Envelope Control unit >
\--------------------------------/

The Volume/Envelope control unit is a simple volume control which can also
do
fade-ins and fade-outs at a configurable rate. The channel volume level is
controlled by a 4-bit delta counter (which can be incremented or decremented
by
1) with an overflow/underflow line. The 1-bit input from the duty cycle
generator or PRNG is multiplied by 15, and binary AND'ed against the volume
control (effectively multiplied by the volume control). Modifications to the
volume control take effect upon the next channel INIT, and if the channel
was
on (length counter status was non-0, and master volume control switch was
on;
see below), then it will trigger a 'zombie mode' volume change (see below).

Channels 1,2,4 - $FF12(NR12)[sq1], $FF17(NR22)[sq2], $FF21(NR42)[noise]
---------------------------------------------
7-4 (Initial) Channel Volume

The volume sweep section consists of a 3-bit down counter(hereafter referred
to
as the 'step length counter') with switchable reload-upon-0, whose initial
value is loaded from the sweep rate value on channel INIT.

Channels 1,2,4 - $FF12(NR12)[sq1], $FF17(NR22)[sq2], $FF21(NR42)[noise]
---------------------------------------------
2-0 Length of each step in sweep

The terminal count (value=0) line of this counter is output to a 1-of-2
selector. This 1-of-2 selector is used to select an upward or downward
volume
sweep, getting the direction from the Volume/envelope register on channel
INIT.

Channels 1,2,4 - $FF12(NR12)[sq1], $FF17(NR22)[sq2], $FF21(NR42)[noise]
---------------------------------------------
3 Volume sweep direction (0: down; 1: up)

if the direction is 0, the counter outputs its signal through the selector
into
the decrease (-) delta terminal of the volume counter. If the direction is
1,
the counter outputs its signal through the selector into the increase (+)
delta
terminal of the volume counter.

SPECULATION: The volume counter itself has an overflow/underflow line, which
is
connected to a switch that prevents the step length counter from reloading
its
original value when it reaches 0. When this occurs, the terminal count line
of
the step length counter is ON steadily, and unless the channel's length
counter
is enabled (and will shut the channel off), the channel enters 'zombie
mode'.

ZOMBIE MODE: UNDEAD CHANNELS!
The channel's volume is now whatever it was set to, or 0/15 if a sweep
occured,
and will sustain that volume indefinitely unless the length counter halts
the
channel. If any envelope register bits are now changed, the volume of the
channel will increase by 1 or 2, looping around to 0 if necessary. (1 if the
channel was INIT-ed with the sweep step number set to 0, 2 if otherwise;
also 2 if the step number has been changed to a non-zero value since the
INIT,
even if it currently is 0)

If the volume sweep direction bit is changed, however, the volume of the
channel will increase by 4 instead of 2, for that write only. Direction of
the
change(1->0 or 0->1) is apparently irrelevant. While in zombie mode, if the
step length register is set to 0, it will have no immediate effect other
than
increasing the volume by 2 (or 4 if the direction was also changed). (but it
WILL change the step size to 1 if the channel is then re-INITed, see above)
Setting the (Initial) Volume to 0 will disable the channel's master channel
control switch, and silence the channel (see below, 'master channel control
switch').

Re-INITing the channel will pull it out of zombie mode: it will turn
envelope
sweeping back on, unless the volume is 0, in which case the master volume
control switch will be off.

/-------------------------------\
< Master Channel Control Switch >
\-------------------------------/
The master channel control switch, which appears at first glance to be
unique
to channel 3, is actually not exclusive to that channel. It is present in
all
of the channels, but is embedded within the Initial Volume control, on the
channels which have an Envelope Control unit (channels 1, 2, and 4).

As mentioned above in the 'Volume/Envelope Control Unit' section, when a
downward envelope sweep occurs, the channel is NOT shut off when the volume
reaches 0. HOWEVER, writing a 0 to the (Initial) Volume section of the
envelope
register will cause that channel's 'hidden' master channel control switch to
be
turned off. This ONLY occurs if 0 is *WRITTEN* to the register, and only if
the
master channel control switch is not already off(it can't be turned off
twice!)
If the switch is off, it can be turned back on by writing any non-0 value to
the (Initial) Volume section of the register.

UNVERIFIED, PLEASE TAKE WITH A GRAIN OF SALT: When the switch for a channel
is
off, it's length counter status flag will be 0. In fact, this may very well
be
the switch turned off by the length counter too.

The switch causes a slight residual DC voltage to be output to the SOx
switches, even if the channel's DAC output is at 0. It makes an audible
click
noise on the speaker/headphones when switched.

At system startup, channel 1's switch is on (turned on by the bootstrap
ROM),
all other channels are off.

/----------------------\
< Frequency Sweep Unit >
\----------------------/
The sweep unit is exclusive to channel 1. The controlling register for the
sweep unit is $FF10(NR10). The sweep unit, on channel INIT, grabs the the 11
bits of channel 1's frequency register, and stores them into a hidden,
internal
register. any writes to the frequency registers during the sweep, will take
effect until the sweep unit makes its next write to those registers,
continuing
the original sweep. IT WILL NOT SWEEP FROM THE NEW FREQUENCY! The sweep unit
has the aforementioned hidden frequency register (an 11-bit accumulator), an
adder, a 3-bit down counter with reload-on-0, a selector switch, and an
up-to-3-bit rightshifter.

The 3-bit down counter controls the frequency of sweep updates. It's initial
(and reload) value is taken from the sweep time register. The value-reload
takes 1 clock cycle.

Channel 1 - $FF10(NR10)[sq1]
---------------------------------------------
6-4 Sweep time(update rate)

The counter is clocked at 128hz, divided from the unified sound clock
(256hz),
so the frequency-of-sweep-update will be:
freq(hz) = 128 / (sweep time + 1)

NOTE: Writing 0 to the sweep time register disables the clock, and therefore
disables sweeping.

The frequency in the accumulator is first rightshifted by up to 7 bits,
controllable by the Sweep RtShift amount register:

Channel 1 - $FF10(NR10)[sq1]
---------------------------------------------
2-0 Sweep RtShift amount

NOTE: Writing 0 to the Sweep RtShift amount disables sweeping. While the
RtShift amount is 0, the sweep time register becomes sort of a length
counter,
and the channel will automatically terminate on it clocking.

NOTE2: When set to sweep upward, the channel will do absolutely nothing on
INIT
unless the current frequency is below the 'sweep threshhold' for that
particular rightshift amount.

The reason for this is because otherwise the channel's NEXT step would
IMMEDIATELY overflow the 11-bit frequency counter.
(frequencies immediately below the threshholds will only play one note,
since
the second step wouldn't overflow, but the third step would, and so only the
first step is played. The sweep unit always works one step ahead of the
current
output, and on the next step outputs that result and calculates the next,
etc.)

The threshholds are:
0: 0x7ff(no threshhold, since sweeping is disabled)
1: 0x556
2: 0x667
3: 0x71d
4: 0x788
5: 0x7c2
6: 0x7e1
7: 0x7f1

The above table is actually unnecessary, I'm just leaving it in as a
reference.

The game 'Metroid 2' runs into this issue in a few places, apparently the
programmers didn't know about the above info. Also, the knife-throwing
monsters
in 'Wario Land: Super Mario Land 3' run into the issue, but there it is
intentionally used to prevent their 'voices' from going too high.

Upon reaching the terminal count (value=0), the counter sends a signal to a
selector, which controls what direction the sweep will be by controlling the
sign bit of the accumulator.

Channel 1 - $FF10(NR10)[sq1]
---------------------------------------------
3 Sweep Direction (1: decrease, 0: increase)

The adder then takes the accumulator, and adds that value to the 11-bit
frequency value stored in registers $FF13 and $FF14. Therefore, because the
registers are modified, the frequency must be rewritten in-between sweeps.

/----------------------\
< Duty Cycle Generator >
\----------------------/
The duty cycle generator is a 3-bit (down?) counter which produces output
depending on the result of some binary operations against the bits of the
counter, the operations selectable by changing the duty cycle bits in
register.

Channels 1,2 - $FF11(NR11)[sq1], $FF16(NR21)[sq2]
---------------------------------------------
7-6 Wave pattern duty

The resulting waves are:

Bits Cyc% 0 1 2 3 4 5 6 7
00 : 12.5% ________==______
01 : 25% ________====____
10 : 50% ____========____
11 : 75% ========____====

= is High
_ is Low

Note that 75% is just a binary NOT against 25%, and that the two are almost
indistinguishable to the human ear.

The duty cycle generator is clocked by the output of the frequency counter
for
channels 1 and 2.

Upon the channel INIT trigger bit being set for either channel 1
or 2, the wave position's incrementing will be delayed by 1/12 of a full
cycle.
IT WILL *NOT* BE RESET TO 0 BY A CHANNEL INIT. 'Gauntlet II' does a very
slick
job of timing? itself around this fact.

Upon system reset, channel 1 will be set to the 50% duty cycle wave, channel
2
to the 12.5% duty cycle wave. (see initial register values)

COMPLETELY UNVERIFIED: In a recent update to NESSOUND.txt, Brad Taylor
demonstrated that the way to reset the position of the two squarewave
channels
on the NES to position 0 is by resetting the timer register. The equivalent
register on the gameboy is PROBABLY the $FF04 (DIV) register, though it
could
also be $FF05 - $FF07 (Timer stuff). This may turn out to be the mysterious
'slick' way that Gauntlet II can 'reset' the position of the squarewave
channels.

PARTIALLY VERIFIED:
The CGB has channels 1 and 2 output in such a way (normal phase reversed on
channel 2 from channel 1) that the two squarewave channels can cancel each
other out completely instead of adding to each other, as on the DMG, MGB,
and
SGB.
I think that one of the reasons Nintendo did this on the CGB was to mess up
the
startup theme of the Galoob 'Game Genie', which is practically inaudible on
the
CGB for this reason! Another, more likely reason could be that they used
some
silicon-saving technique on the duty cycle generators which necessitated
opposite phase on the two squarewave channels.
This is noticible in quite a few official Nintendo-approved games, but the
game
which demonstrates it particularly vividly is "Lock n' Chase". It sounds
absoluetly HORRIBLE on a CGB!

/-------------------------------\
< PseudoRandom Number Generator >
\-------------------------------/
The noise channel has a 1-bit pseudo-random number generator, or PRNG. This
particular type of PRNG is called an LFSR, a Linear Feedback Shift Register.
It's based on a 15 or 7-bit shift register, and an exclusive OR gate (XOR).
The
mode is selectable by the Shift register width selector.

Channel 4 - $FF22(NR43)[noise]
---------------------------------------------
3 Shift Register width (0: 15 bits; 1: 7 bits)

The following diagram shows where the XOR taps are taken off the shift
register to produce the 1-bit pseudo-random number sequences for each mode.

mode <-----
---- FEDCBA9876543210
32K %*.............R
512 XXXXXXXX%*.....R

X- N/A
%- output and XOR tap
*- XOR tap
R- result of XOR, to be shifted in

The current result of the XOR will be transferred into bit position 0 of the
shift register upon the next shift cycle. The 1-bit 'random' output is taken
from the output, is inverted, then is sent to the volume/envelope hardware
for
the noise channel.

VERIFIED: Upon the channel INIT trigger bit being set for this channel (4),
the PRNG will be reloaded with a value of 0xFF. (Kirby 2)
NOTE: There will be a 16-clock delay before the PRNG outputs any non-0 data
after an INIT. This means the value loaded on channel INIT isn't 0x01 as
previously written here, but is 0xFF. this will cause the channel to have a
value of 0x01 16 clocks later. Again, thanks to beware for pointing this
out.

On system reset, this shift register is loaded with a value of 1.

/---------------------\
< Wave Pattern Memory >
\---------------------/
This is the 16-byte long 'hidden' internal memory area (hereafter referred
to
as 'wave pattern memory'), containing the 32 4-bit samples for channel 3. It
can be written to by writing the 16-byte sample data into the wave pattern
load
register.

Channel 3 - Wave pattern load register - $FF30-$FF3F
----------------------------------------------
FOR EACH BYTE IN $FF30-$FF3F:
7-4 Sample 0
3-0 Sample 1

Setting the 'init' bit [bit 7] in $FF1E to 1 will slightly scramble the
contents at location $FF30-$FF3F, but the wave pattern memory will retain
the
proper values.
This area cannot be written to while channel 3's master control switch is
on.
UNVERIFIED: If it IS written to when the control is on, the written values
will
be ignored.
Sample playback is possible using this register, by turning off the switch
and
writing the next 16 4-bit samples, and turning it back on. However, doing
this
will create some click-distortion from the switch itself (especially on
DMGs),
and the first sample immediately after the switch is turned back on will be
replaced (due to capacitance somewhere or possibly a pointer pointing
somewhere
unexpected) by the last COMPLETELY played back (partially played doesn't
count)
sample before the switch was shut off. (Thanks Jeff Frohwein for a nice
image
demonstrating this)

UNVERIFIED: The 1-sample error is carried over to successive loops of the
wave pattern data.

On system power-on of the CGB, this internal area is loaded with:
(all hex)
00 FF 00 FF 00 FF 00 FF 00 FF 00 FF 00 FF 00 FF

On system power-on of the SGB (and SGB2?) this internal area is loaded with:
00 FF 00 FB 00 FF 00 FF 00 FF 00 FF 00 FF 00 FF

On system power-on of the DMG (and MGB???), the internal area isn't loaded
with any particular value, however due to some unusual properties of the
memory
in question, the values present will almost always be roughly the same.
The game "R-Type", due to a programming error, doesn't load this area with
anything, and therefore the initial value is played. When "R-Type" was
re-released for the GBC in "R-Type DX", Irem made a very good approximation
of
the DMG's initial Wave pattern memory values. Those values are:
0xac, 0xdd, 0xda, 0x48, 0x36, 0x02, 0xcf, 0x16,
0x2c, 0x04, 0xe5, 0x2c, 0xac, 0xdd, 0xda, 0x48

However on actual DMG hardware, the values are pretty much completely
random,
in a pattern unique to each Gameboy unit. By this I mean that, on a
particular
Gameboy, bits which start as 1 almost always start as 1, and bits which
start
as 0 almost always start as 0. There IS some variation, but the values are
roughly the same every time. It is sort of a 'Gameboy fingerprint'.

I dumped them 4 times from my DMG-005, the dumps are:
84 40 43 AA 2D 78 92 3C 60 59 59 B0 34 B8 2E DA
04 CA 02 EA 2D 7E 92 3C 60 59 59 BA 24 B8 2E DA
04 CA 42 AA 2D 78 92 3C 60 59 59 BA 34 B8 2E DA
15 CD 01 AA 0D 7F 92 BC 60 CB 19 BA A0 BC 2E FE

I also dumped them 4 times from my DMG-006:
8C BC 04 73 0B 8E 35 F8 C9 B7 68 19 80 73 CC 88
8C BC 00 73 0B 8E 35 F8 C9 B7 68 19 80 73 C4 88
12 36 00 BB 08 CE 91 FE 01 BF 38 BB 88 F7 24 BB
8C B4 04 7B 0B 8E 25 FC C9 B7 78 19 80 73 C4 88

One can easily see that though no two dumps are the same, they follow a
general
pattern, which seems to be unique to each Gameboy unit.

/--------------------------------------\
< Wave Pattern Playback / Shifter Unit >
\--------------------------------------/
This is effectively a 5-bit counter, which acts as a pointer to the current
4-bit sample in the 16-byte, 32-sample wave pattern memory. Every clock from
the programmable timer will cause a 4-bit sample (the wavepattern's
[high-4-bits-of-counter]st byte's high or low 4 bits [depending on whether
the
counter's low bit is 0 or 1, respectively]) to be sent to the volume shifter
unit. The volume shifter unit, depending on it's register, will output
either
0, the 4-bit sample, or the sample rightshifted by 1 or 2. This 4-bit result
is
then sent to the DAC.

Channel 3 - $FF1C(NR32)[wave]
---------------------------------------------
6-5 Volume Level (0: Mute; 1: 100%; 2: 50% [rtshift 1]; 3: 25% [rtshift 2])

UNVERIFIED: On system startup, this counter is pointing to the first sample.

/------------------------\
< SO1 / SO2 Control Unit >
\------------------------/
The SO1/SO2 control unit is a set of 8 on/off switches which turn on and off
each channel's output to SO1(right) and SO2(left), another two switches
which
control Vin's output to SO1 and SO2, and the master output volume for each
SO
'channel'.

Bits 7 and 3 are Vin output control switches, they have roughly the same
residual voltage on them as the master volume control switches of the other
channels. Like the other channels, they are added to SOx before the main
output
level (volume) control, and their volume is multiplied/regulated by the main
volume controls in exactly the same way as the rest of the channels are.
No known game actually uses them for their intended (Vin) purpose.
(One Public Domain game does however use them for sound in a unique way, by
taking advantage of their residual voltage and the main output level
control:
'The Winnowing', by Plasma Works)

In short, Vin acts just like any other one of the channels in its output
switching behavior. It just never has anything on it except for residual
voltage.

Bits 6-4 and 2-0 regulate the volume on each channel in this fashion:
Where SOx is the added result of all of the DACs and Vin (if selected) for
output channel x:
output volume = volume of SOx + (volume of SOx * Main Output Level of SOx)
Thus, these controls cannot completely mute a particular SOx output channel.

These switches control raw voltage, so if a channel's master channel control
switch is on(slightly raising the voltage output by that channel), turning
off
(or on) that channel's SOx output switches will result in clicks on the
respective speaker/headphone as the voltage suddenly drops or is raised. If
the
master output control switch is off, no clicking can occur, as the raised
voltage never gets this far.

/--------------------------\
< ORGANIZATION OF CHANNELS >
\--------------------------/
sweep unit --\
freq counter ----*--Duty cycle generator-- TO |A|
length counter -/ or
PRNG

master channel ctrl --------\
|A| -----[volume/envelope]--- DAC ----*-----\-----\
| |
Specific Channel SOx Selects----*-----*
| |
Vin S0x Selects ---*-----*
| |
Main output volume controls -> SO1+ SO2+
| |
Volume Knob and various other circuity -> >+++<
| |
Right Left

[volume/envelope]
>(Init causes everything to be read from regs)
(to master channel ctrl)
/
-[---------------------volume control------------]---...
Step length counter +<--->-
\ /
Direction select

* = switch, off if side input is 0
+ = Volume Control

In short, the output order for all the channels is:
[4-bit DAC] -> [Master channel switch] -> [SO1/SO2 select switches] =>
[Vin select switches] => [Master Output L/R Volume Control] => Volume Knob
=>
High/Lowpass Filter(s) => Headphone Jack => (if no headphone plug is
inserted)
Mixing Circuitry -> Front Speaker

=> - stereo connection
-> - mono connection

The SO1/SO2 output lines of the processor are connected to a set of pull-up
resistors, and one (or more) high/lowpass resistor/capacitor combinations,
which is then connected to the earphone terminal. A seperate tap of the SOx
lines mixes the two channels together, and runs through a
break-on-earphone-plug-presence switch in the earphone jack, and goes to the
speaker on the front of the unit.
The High/Lowpass filters used by the various iterations of the Gameboy
differ:
The DMG (and MGB?) has a lowpass filter with a cutoff somewhere above
22050hz?,
and no noticable highpass filter.
The CGB has has a lowpass filter with a cutoff somewhere above 22050hz?, and
also has a highpass filter with a cutoff of 60hz, whose purpose was probably
to
reduce the roughly 60hz LCD refresh? noise on the CGB, a job at which it
fails
utterly.
The highpass filter on the CGB severely impairs the bass sound produced by
the
Gameboy, but people have discovered that a little hardware hacking can
bypass
the highpass filter and get much better quality sound output. I won't go
into
the details here, just search on your favorite search engine for 'GB
Prosound'.

PARTIALLY VERIFIED:On older versions (pre-DMG-CPU-05?) of the DMG, the scale
of
the DAC used on the various channels is semi-logarithmic instead of truly
linear. Later Gameboy models (MGB,SGB,CGB,GBA) used either better pull-up
resistor/capacitor and/or analog output DACs, and are almost perfectly
linear.
(Thanks Jeff Frohwein)
Here are some scales for demonstration:

TRUE Logarithmic:
0---------------1--------------2-------------3------------4-----------5----------6---------7--------8-------9------A-----B----C---D--E-F

TRUE Linear:
0--------1--------2--------3--------4--------5--------6--------7--------8--------9--------A--------B--------C--------D--------E--------F

Semi-Logarithmic:
0-----------1-----------2-----------3----------4---------5---------6---------7--------8-------9-------A-------B------C-----D-----E-----F

/-------------------------------------------\
< **Patent Numbers (for those interested)** >
\-------------------------------------------/
#5,184,830 - Compact Hand-held Video Game System
This details a lot of information about memory maps, video hardware, and has
flowcharts explaining the bootstrap ROM.

#5,134,391 - System for preventing the use of an unauthorized external
memory
This goes into the gory details about how the gameboy's bootstrap ROM works.

#5,095,798 - Electronic Gaming Device with Pseudo-Stereophonic Sound
Generating
Capabilities
This gives a lot of information about the layout of the sound system in the
Gameboy.

/-------------\
< **Credits** >
\-------------/
This document written by Jonathan Gevaryahu, AKA Lord Nightmare
lord_nightmare at users dot sourceforge dot net

Thanks to all the authors whose information I borrowed in order to make this
document. Without their work, this doc would never have existed!

Special Thanks to the people in #gameboy on EFNET for helping me out on a
few
points.

Special Thanks to laguna for writing (most of) gnuboy and getting me
interested
in this documentation project in the first place.

Special Thanks to beware for sharing his bgb sound generator source code,
and
coming up with a MUCH more plausable timing scheme for the sweep/envelope
systems. Thanks beware!

Special Thanks to Joshua Wise for hosting a mirror of this file.