Skip to content

Commit b51f3b6

Browse files
ISSOtmISSOtm
committed
[WIP] Overhaul audio section
1 parent d912688 commit b51f3b6

11 files changed

+1790
-421
lines changed

‎src/APU_details.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# APU details
2+
3+
## Pitfalls
4+
5+
- Enabling or disabling a DAC (resetting NR30 bit 7 or writing %0000
6+
0XXX to NRx2 for other channels), adding or removing it using NR51,
7+
or changing the volume in NR50, will cause an audio pop. (This
8+
causes a change in DC offset, which is smoothed out by a high-pass
9+
circuit over time, but still creates a pop)
10+
- The final output goes through a high-pass filter, which is more
11+
aggressive on GBA than on GBC, which is more aggressive than on DMG.
12+
(What this means is that the output is "pulled" towards 0V with
13+
various degrees of "aggressiveness")
14+
- When first starting up a pulse channel, it will *always* output a
15+
(digital) zero.
16+
- The pulse channels' "duty step" (at which position in the duty
17+
cycle they are) can't be reset. The exception to this is turning
18+
off the APU, which causes them to start over from 0 when turning it
19+
on.
20+
- Restarting a pulse channel causes its "duty step timer" to reset,
21+
meaning that "tickling" a pulse channel regularly enough will
22+
cause its "duty step" to never advance.
23+
- When restarting CH3, it resumes playing the last 4-bit sample it
24+
read from wave RAM, or 0 if no sample has been read since APU reset.
25+
(Sample latching is independent of output level control in NR32.)
26+
After the latched sample completes, it starts with the second sample
27+
in wave RAM (low 4 bits of $FF30). The first sample (high 4 bits of
28+
$FF30) is played last.
29+
- CH3 output level control does not, in fact, alter the output level.
30+
It shifts the **digital** value CH3 is outputting (read below), not
31+
the analog value.
32+
- On GBA, CH3 is inverted. This causes the channel to output a loud
33+
spike when disabled; it's a good idea to "remove" the channel
34+
using NR51 before refreshing wave RAM.
35+
36+
## APU detailed architecture
37+
38+
{{#include imgs/apu_detailed.svg:2:}}
39+
40+
*Source: Lior "LIJI32" Halphon*
41+
42+
43+
Not addressed in this infographic is the Game Boy's Channel 5, which is an analog channel driven directly by the VIN pin in the cartridge connector.
44+
45+
The digital outputs of the 4 channels can be read using two undocumented debug registers that were given the unofficial names PCM12 and PCM34, and were introduced in the Game Boy Color.
46+
47+
The digital behavior of the APU can be relatively easily verified due to the fact that on CGB and newer models, all of its outputs (digital waveforms, DAC enable bits, NR50, NR51) can be read in real time.
48+
49+
Can be used to tell if a channel is active.
50+
A channel is activated by a write to NRx4's MSB.
51+
The length timer, frequency sweep, and turning off its DAC can all deactivate a channel.
52+
53+
A simple analog amplifier.
54+
Two 3-bit values from NR50 are used to amplify the two inputs.
55+
A value of 0 is treated as a volume of 1, and a value of 7 is treated as 8, so the amplifier never mutes a non-silent input.
56+
57+
The 4 DACs are enabled by NR12, NR22, NR30, and NR42.
58+
If a DAC is enabled, the digital range 0 to F is lineraly translated to the analog range -1 to 1, in arbitrary units.
59+
If a DAC is disabled, it fades to an analog value of 0.
60+
The nature of this fade is not entirely deterministic and varies between models.
61+
On the AGB and newer, the DACs are emulated digitally such that a disabled DAC outputs the same amplitude as an enabled DAC with an input of 0.
62+
Additionally, CH3's output is inverted on these models.
63+
64+
The mixer takes an 8-bit bitmap from NR51 to sum the 4 channels into two outputs—left and right.
65+
Each output channel goes through a high-pass filter to remove the DC offset created by inactive channels with an enabled DAC, and off-center waveforms.
66+
67+
### Game Boy, Game Boy Color
68+
69+
Each of the 4 channels work pretty identically. First, there's a
70+
"generation" circuit, which usually outputs either a 0 or another
71+
value (CH3 differs in that it can output multiple values, but
72+
regardless). That value is digital, and can range between 0 and 0xF.
73+
This is then fed to a
74+
[DAC](https://en.wikipedia.org/wiki/Digital-to-analog_converter), which
75+
maps this to an analog value; 7 maps to the lowest (negative) voltage, 0
76+
to the highest (positive) one. Finally, all channels are mixed through
77+
NR51, scaled through NR50, and sent to the output.
78+
79+
Each DAC is controlled independently from the generation circuit. For
80+
CH3, the DAC is controlled by NR30 bit 7; for other channels, the DAC is
81+
turned on unless bits 3-7 of NRx2 are reset, and the envelope will be
82+
set to `[NRx2] >> 4`. (Note: the envelope sweep function changes the
83+
envelope, but not the value in NRx2! It won't disable the DAC, either.)
84+
The generation circuits are turned on by restarting them for the first
85+
time, and this is what sets the corresponding bit in NR52. Yes, it's
86+
possible to turn on a DAC but not the generation circuit. Finally,
87+
disabling a DAC also kills the generation circuit.
88+
89+
Note that each DAC has a DC offset, so enabling, disabling, adding to or
90+
removing from NR51, will all cause an audio pop; changing the volume in
91+
NR50 will as well.
92+
93+
Finally, all the output goes through a high-pass filter to remove the DC
94+
offsets from the DACs.
95+
96+
### Game Boy Advance
97+
98+
The APU was reworked pretty heavily for the GBA. Instead of mixing being
99+
done analogically, it's instead done digitally; then, sound is
100+
converted to an analog signal and an offset is added (see `SOUNDBIAS` in
101+
[GBATEK](http://problemkaputt.de/gbatek.htm#gbasoundcontrolregisters)
102+
for more details).
103+
104+
This means that the GBA APU has no DACs.
105+
This can be retro-fit into the GB APU model as if all DACs were always on.
106+
107+
## Finer technical explanation
108+
109+
### DIV-APU
110+
111+
A "DIV-APU" counter is increased every time `DIV`'s bit 4 (5 in [double-speed mode](<#FF4D - KEY1 - CGB Mode Only - Prepare Speed Switch>)) goes from 1 to 0, therefore at a frequency of 512 Hz (regardless of whether double-speed is active).
112+
Thus, the counter can be made to increase faster by writing to `DIV` while the relevant bit is set (which clears `DIV`, and triggers the falling edge).
113+
114+
Some events are tied to the DIV-APU counter:
115+
116+
Event | Every N ticks | Frequency[^div_apu_freq]
117+
---------------|---------------|-------------------------
118+
Envelope sweep | 8 | 64 Hz
119+
Sound length | 2 | 256 Hz
120+
CH1 freq sweep | 4 | 128 Hz
121+
122+
[^div_apu_freq]:
123+
Indicated values are under normal operation; the frequencies will obviously differ if writing to `DIV` to increase the counter faster.

‎src/Audio.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Audio Overview
2+
3+
Game Boy audio is sometimes called "8-bit", but this doesn't mean much: the term is used to designate audio similar to that produced by 8-bit consoles.
4+
5+
A better description would be "chiptune": tunes produced by a chip.
6+
This section describes how audio is generated on the Game Boy.
7+
8+
## Architecture
9+
10+
{{#include imgs/apu_overview.svg:2:}}
11+
12+
The Game Boy has four sound generation units, called **channels** 1 through 4, notated "CH1", "CH2", etc.
13+
Unlike other sound chips, such as the SNES' S-DSP or the Atari 5200's POKEY, each sound channel is largely different from the others.
14+
15+
Each channel generates an electronic signal; these signals are then mixed into two new channels (for stereo: one for the left ear, one for the right ear), which are then individually amplified, and then output either to the headphone jack, or the speaker[^speaker_mono].
16+
17+
Channels 1 and 2, the "pulse channels", produce [pulse (rectangular) waves](https://en.wikipedia.org/wiki/Pulse_wave).
18+
Channel 3, the "wave" channel, produces user-defined waves.
19+
Channel 4 is the "[noise](https://en.wikipedia.org/wiki/Noise_in_music)" channel, producing a pseudo-random wave.
20+
21+
The VIN channel is a signal received directly from the cartridge, allowing external hardware to supply a fifth sound channel.
22+
No licensed games used this feature, and it was omitted from the Game Boy Advance.
23+
24+
::: tip POCKET MUSIC
25+
26+
Despite rumors, *Pocket Music* does not use VIN. It refuses to run on the GBA for a different reason:
27+
the developer couldn't figure out how to silence buzzing associated with sample playback on the wave channel.
28+
29+
:::
30+
31+
[^speaker_mono]:
32+
The speaker merges back the two channels, losing the stereo aspect entirely.
33+
34+
## Common concepts
35+
36+
### APU
37+
38+
The Game Boy's sound chip is called the <abbr title="Audio Processing Unit">APU</abbr>.
39+
40+
The APU runs off the same master clock as the rest of the Game Boy, which is to say, it is fully synced with the CPU and [PPU](<#Rendering Overview>).
41+
This also means that the APU runs about 2.4% faster on the SGB1, increasing frequencies by as much and thus sounding slightly higher-pitched.
42+
The SGB2 does not suffer from this issue.
43+
44+
The APU processes a lot of events at a fixed rate, which depends on the type of event.
45+
Thus, the APU interfaces use durations instead of frequencies, which may be confusing as signal theory and music are more typically based on the latter.
46+
Thus, durations will be expressed from their frequencies: for example, a "256 Hz tick" means "1/256th of a second".
47+
48+
The length of ticks is not affected by [CGB double speed](<#FF4D - KEY1 - CGB Mode Only - Prepare Speed Switch>), so the APU works just the same regardless of CPU speed.
49+
50+
::: warning
51+
52+
The Game Boy's APU is actually full of tricky details; this chapter will mostly describe the intended / common behavior, and often paper over bugs & quirks.
53+
Readers wishing to learn more should read the [APU details](<#APU details>) chapter.
54+
55+
:::
56+
57+
### Envelope
58+
59+
Each channel's [**envelope**](https://en.wikipedia.org/wiki/Envelope_(music)) can be configured.
60+
A signal's [envelope](https://en.wikipedia.org/wiki/Envelope_(waves)) is, roughly speaking, the variation of the signal's amplitude.
61+
On the GB, "envelope" basically designates the channel's loudness.
62+
63+
All channels can have their envelope controlled to modulate their volume (CH3 less precisely than other channels).
64+
In addition, all channels but CH3 benefit from a functionality called **envelope sweep**, which automatically adjusts the envelope over time.
65+
The parameters that can be controlled are how many times the envelope will be stepped, in which direction, and how long between steps.
66+
Envelope sweep ticks at 64 Hz, and every 1&ndash;7 of those ticks, the envelope will be increased or decreased.
67+
68+
### Sound length
69+
70+
All channels can be set to automatically shut themselves down after a certain amount of time.
71+
This can be used to time the "sustain" part of ADSR, though the sound will cut fairly abruptly once the sound length "expires", instead of decaying.
72+
73+
A channel's sound length is initially set between 0 and 63, and, if enabled, ticks up[^len_cnt_dir] at 256 Hz (tied to [DIV-APU](<#DIV-APU>)).
74+
When the counter reaches 64, the channel is turned off.
75+
76+
[^len_cnt_dir]:
77+
Actually, the sound length is inverted when written, and *that* ticks down until it reaches 0.
78+
But the effect is as if the counter ticked up.
79+
80+
### Wave length
81+
82+
Music notes and audio waves are typically manipulated in terms of *frequency*, i.e. how often the signal repeats per second.
83+
However, as explained above, the Game Boy APU primarily works with durations; thus, *wave length* is used instead of frequency.[^len_raw]
84+
85+
Wave length, the amount of time before the signal repeats, is the inverse of frequency, i.e. `len = 1 ∕ f`, and `f = 1 ∕ len`.
86+
87+
[^len_raw]:
88+
Actually, the APU interfaces don't store any wave lengths either, but a value that is more akin to a wave length than a frequency.
89+
90+
### Triggering
91+
92+
Some writes to APU registers take effect immediately (such as any frequency changes), but others are buffered until the channel is (re-)*triggered*.
93+
94+
Triggering the channel (re)loads a lot of parameters, restarts playback[^pulse_restart], and turns the channel on[^trig_dac_off].
95+
96+
[^pulse_restart]:
97+
Except for pulse channels, whose index into their waves is only ever reset by turning the APU off.
98+
This is not noticeable when playing sound, and only matters for "advanced" APU usage.
99+
100+
[^trig_dac_off]:
101+
If the channel's DAC is off (TODO: link to explanation), the channel will not turn on.

‎src/Power_Up_Sequence.md

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ DMG | 256 | |
1414
MGB | 256 | One-byte difference to DMG
1515
SGB | 256 | Only forwards logo to SGB BIOS, performs no checks
1616
SGB2 | 256 | Same difference to SGB than between MGB and DMG
17-
CGB0 | 256 + 1792 | Does not init [wave RAM](<#FF30-FF3F - Wave Pattern RAM>)
17+
CGB0 | 256 + 1792 | Does not init [wave RAM](<#FF30-FF3F - Wave Pattern RAM (R/W)>)
1818
CGB | 256 + 1792 | Split in two parts, with the cartridge header in the middle
1919
AGB | 256 + 1792 | Fixes ["logo TOCTTOU"](<#Bypass>)
2020

@@ -95,7 +95,7 @@ Like all other boot ROMs, the last thing the color boot ROMs do is hand off exec
9595
Like the DMG0 boot ROM, some early CGBs contain a different boot ROM.
9696
Unlike DMG0 and DMG, the differences between the CGB0 and CGB boot ROM are very minor, with no change in the layout of the ROM.
9797

98-
The most notable change is that the CGB0 boot ROM does *not* init [wave RAM](<#FF30-FF3F - Wave Pattern RAM>).
98+
The most notable change is that the CGB0 boot ROM does *not* init [wave RAM](<#FF30-FF3F - Wave Pattern RAM (R/W)>).
9999
This is known to cause, for example, a different title screen music in the game *R-Type*.
100100

101101
The CGB0 boot ROM also writes copies of other variables to some locations in WRAM that are not otherwise read anywhere.
@@ -350,23 +350,23 @@ The table above was obtained from Mooneye-GB tests [`acceptance/boot_hwio-dmg0`]
350350
[`NR10`]: <#FF10 - NR10 - Channel 1 Sweep register (R/W)>
351351
[`NR11`]: <#FF11 - NR11 - Channel 1 Sound length/Wave pattern duty (R/W)>
352352
[`NR12`]: <#FF12 - NR12 - Channel 1 Volume Envelope (R/W)>
353-
[`NR13`]: <#FF13 - NR13 - Channel 1 Frequency lo (Write Only)>
354-
[`NR14`]: <#FF14 - NR14 - Channel 1 Frequency hi (R/W)>
355-
[`NR21`]: <#FF16 - NR21 - Channel 2 Sound Length/Wave Pattern Duty (R/W)>
356-
[`NR22`]: <#FF17 - NR22 - Channel 2 Volume Envelope (R/W)>
357-
[`NR23`]: <#FF18 - NR23 - Channel 2 Frequency lo data (W)>
358-
[`NR24`]: <#FF19 - NR24 - Channel 2 Frequency hi data (R/W)>
359-
[`NR30`]: <#FF1A - NR30 - Channel 3 Sound on/off (R/W)>
353+
[`NR13`]: <#FF13 - NR13 - Channel 1 Frequency Control low (Write Only)>
354+
[`NR14`]: <#FF14 - NR14 - Channel 1 Control (R/W)>
355+
[`NR21`]: <#Sound Channel 2 - Tone>
356+
[`NR22`]: <#Sound Channel 2 - Tone>
357+
[`NR23`]: <#Sound Channel 2 - Tone>
358+
[`NR24`]: <#Sound Channel 2 - Tone>
359+
[`NR30`]: <#FF1A - NR30 - Channel 3 DAC Enable (R/W)>
360360
[`NR31`]: <#FF1B - NR31 - Channel 3 Sound Length (W)>
361-
[`NR32`]: <#FF1C - NR32 - Channel 3 Select output level (R/W)>
362-
[`NR33`]: <#FF1D - NR33 - Channel 3 Frequency's lower data (W)>
363-
[`NR34`]: <#FF1E - NR34 - Channel 3 Frequency's higher data (R/W)>
361+
[`NR32`]: <#FF1C - NR32 - Channel 3 Output Level (R/W)>
362+
[`NR33`]: <#FF1D - NR33 - Channel 3 Frequency Control Low (W)>
363+
[`NR34`]: <#FF1E - NR34 - Channel 3 Control (R/W)>
364364
[`NR41`]: <#FF20 - NR41 - Channel 4 Sound Length (W)>
365365
[`NR42`]: <#FF21 - NR42 - Channel 4 Volume Envelope (R/W)>
366-
[`NR43`]: <#FF22 - NR43 - Channel 4 Polynomial Counter (R/W)>
367-
[`NR44`]: <#FF23 - NR44 - Channel 4 Counter/consecutive; Inital (R/W)>
368-
[`NR50`]: <#FF24 - NR50 - Channel control / ON-OFF / Volume (R/W)>
369-
[`NR51`]: <#FF25 - NR51 - Selection of Sound output terminal (R/W)>
366+
[`NR43`]: <#FF22 - NR43 - Channel 4 Randomness Control (R/W)>
367+
[`NR44`]: <#FF23 - NR44 - Channel 4 Control (R/W)>
368+
[`NR50`]: <#FF24 - NR50 - Master volume & VIN mixing control (R/W)>
369+
[`NR51`]: <#FF25 - NR51 - Mixing control (R/W)>
370370
[`NR52`]: <#FF26 - NR52 - Sound on/off>
371371
[`LCDC`]: <#FF40 - LCDC (LCD Control) (R/W)>
372372
[`STAT`]: <#FF41 - STAT (LCD Status) (R/W)>

‎src/SUMMARY.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@
2424
- [Scrolling](./Scrolling.md)
2525
- [Palettes](./Palettes.md)
2626
- [Pixel FIFO](./pixel_fifo.md)
27-
- [Sound Controller](./Sound_Controller.md)
27+
- [Audio](./Audio.md)
28+
- [Sound Registers](./Sound_Registers.md)
29+
- [APU details](./APU_details.md)
2830
- [Joypad Input](./Joypad_Input.md)
2931
- [Serial Data Transfer](./Serial_Data_Transfer_(Link_Cable).md)
3032
- [Timer and Divider Registers](./Timer_and_Divider_Registers.md)

0 commit comments

Comments
 (0)