feat(audio): implement PSG pulse channel 2

docs/architecture.md

@@ -54,9 +54,10 @@ The repository is a Cargo workspace with three crates:
 | `crates/gba-core/src/cpu/fetch_boundary_tests.rs` | Actual fetch-region snapshots, split refills, IWRAM lane requirements, ROM-window boundaries, and nominal timing |
 | `crates/gba-core/src/io.rs` | I/O registers, timers, HALT/STOP wake-up, next-event bounds, and IRQ latches |
 | `crates/gba-core/src/audio.rs` | Direct Sound state, PSG sequencer, idle channel/wave banks, and instantaneous stereo mixing |
-| `crates/gba-core/src/audio/pulse.rs` | Pulse channel 1 oscillator, length, envelope, sweep, and status |
+| `crates/gba-core/src/audio/pulse.rs` | Shared pulse oscillator, length, envelope, and status; sweep is mapped only for channel 1 |
 | `crates/gba-core/src/audio/pulse/tests.rs` | Exhaustive frequency/duty arithmetic and original modulation edge tests |
 | `crates/gba-core/tests/pulse_sound.rs` | Register masks, stereo mixing, sequencer clocks, idle modes, batching, and explicit limits |
+| `crates/gba-core/tests/pulse_sound/channel2.rs` | Channel 2 mapping, register gaps, independent state, shared clocks, and sum-before-rounding mixing |
 | `crates/gba-core/tests/direct_sound.rs` | FIFO lanes/reset, signed mixing, timer selection, DMA refill, and HALT/STOP |
 | `crates/gba-core/src/memory/audio_step_tests.rs` | Audio access phases, shadow validation, and CPU/DMA failure rollback |
 | `crates/gba-core/src/io/inactive.rs` | Disconnected serial initialization with explicit unsupported-activity validation |

docs/hardware/audio.md

@@ -1,7 +1,7 @@
 # Audio device subset
 
-The core models Direct Sound A/B, bounded sound DMA, and programmable sound generator (PSG) pulse channel 1.
-It does not produce desktop audio. PSG channels 2–4 remain unsupported.
+The core models Direct Sound A/B, bounded sound DMA, and programmable sound generator (PSG) pulse channels 1 and 2.
+It does not produce desktop audio. PSG wave channel 3 and noise channel 4 remain unsupported.
 `Memory::audio_level()` exposes the current digital stereo level for deterministic inspection, not a continuous sample stream.
 
 ## Registers and PSG state
@@ -9,14 +9,17 @@ It does not produce desktop audio. PSG channels 2–4 remain unsupported.
 | Address | Behavior |
 | --- | --- |
 | `0x04000060..0x04000065` | Pulse channel 1 sweep, duty, length, envelope, frequency, and trigger |
-| `0x04000066..0x04000081` | Idle channel 2–4 configuration and PSG mixer controls |
+| `0x04000068..0x04000069` | Pulse channel 2 duty, length, and envelope |
+| `0x0400006c..0x0400006d` | Pulse channel 2 frequency and trigger; no sweep unit |
+| `0x04000070..0x04000081` | Idle channel 3–4 configuration and PSG mixer controls |
 | `0x04000082` (`SOUNDCNT_H`) | Mixing, routing, timer selection, and FIFO reset strobes; readback mask `0x770f` |
-| `0x04000084` (`SOUNDCNT_X`) | Master enable in bit 7; read-only channel 1 activity in bit 0; channels 2–4 remain inactive |
+| `0x04000084` (`SOUNDCNT_X`) | Master enable in bit 7; read-only channel 1/2 activity in bits 0/1; channels 3–4 remain inactive |
 | `0x04000088` (`SOUNDBIAS`) | Bias/resolution configuration with mask `0xc3fe` |
 | `0x04000090..0x0400009f` | CPU wave RAM window, opposite the bank selected by `SOUND3CNT_L` bit 6 |
 | `0x040000a0..0x040000a7` | FIFO A/B writes with byte, halfword, and word access boundaries preserved |
 
 Unused mapped register bytes read zero and ignore writes.
+The halfwords at `0x04000066`, `0x0400006a`, and `0x0400006e` do not alias pulse registers or enable channel 2 sweep.
 FIFO reads and the `0x0400008c..0x0400008f` gap remain explicit unmapped-access errors; no FIFO open-bus value is invented.
 Raw memory starts with zero sound state. RegisterRamReset bit 6 sets the functional bias default to `0x0200`.
 
@@ -25,19 +28,23 @@ The CPU then accesses wave bank 1. Idle bank selection can expose bank 0 after m
 The original BIOS reset clears bank 1 and both FIFO queues. It retains bank 0 and any separate in-flight playback word.
 This is a functional reset subset, not a claim of complete firmware ordering or sound-reset equivalence.
 
-An enabled channel 2–4 trigger returns `MemoryError::UnsupportedIo` with the exact address and value.
+An enabled channel 3–4 trigger returns `MemoryError::UnsupportedIo` with the exact address and value.
 This applies even when the configured channel would be inaudible. All PSG writes are ignored while master sound is disabled.
 Reserved PSG volume selection 3 is rejected while master sound is enabled, including enable after disabled configuration.
-Idle channel 2–4 writes do not imply playback support.
+Idle channel 3–4 writes do not imply playback support.
 
-## Pulse channel 1
+## Pulse channels 1 and 2
 
-Channel 1 has four duty patterns: 12.5%, 25%, 50%, and 75%.
+Each pulse channel has four duty patterns: 12.5%, 25%, 50%, and 75%.
 Its eight-position waveform advances every `16 * (2048 - frequency)` system clocks.
+The channels keep independent frequency, duty position, length, envelope, logical DAC gate, and activity state.
+Only channel 1 has sweep. Channel 2 reuses the pulse engine without any mapped sweep register.
 No general-purpose timer must be enabled for PSG playback.
 Frequency writes change the next oscillator reload, not the remaining current interval.
-A trigger reloads the oscillator timer, envelope volume, envelope timer, and sweep shadow/timer state.
-Retrigger preserves the duty position. Master disable resets it.
+A trigger reloads that channel's oscillator timer, envelope volume, and envelope timer.
+Channel 1 also initializes its sweep shadow/timer state.
+Retrigger preserves that channel's duty position and does not restart the other channel.
+Master disable resets both pulse channels.
 
 The modulation sequencer receives a 512 Hz clock, once per 32768 system clocks:
 
@@ -49,7 +56,8 @@ The modulation sequencer receives a 512 Hz clock, once per 32768 system clocks:
 
 The divider starts at synthetic phase zero and continues while master sound is disabled.
 Master enable sets the next sequencer step to zero without resetting that divider.
-Channel trigger does not reset the shared sequencer. HALT continues its clocks; STOP freezes them.
+Neither channel trigger resets the shared sequencer. Both receive length/envelope clocks at the same sequencer phase.
+HALT continues these clocks; STOP freezes them.
 Waveform advancement uses arithmetic batches between sequencer events, not a loop for every system clock.
 
 Length writes load `64 - length_field`. Enabled length expiry clears the channel activity flag.
@@ -64,7 +72,7 @@ Reactivating a stopped envelope loads its new countdown. Trigger loads its confi
 Clearing envelope bits 3–7 disables the channel; setting them again requires a trigger to restart it.
 This is the logical gate often called DAC enable in Game Boy references, not a separate physical GBA DAC.
 
-Sweep uses a shadow frequency independent of later frequency-register writes.
+Channel 1 sweep uses a shadow frequency independent of later frequency-register writes.
 A nonzero shift checks overflow immediately at trigger.
 Timed sweep updates check overflow both before and after committing the new frequency.
 A result above 2047 disables the channel. Period zero suppresses periodic frequency changes, not the trigger-time check.
@@ -120,10 +128,12 @@ Sub-instruction DMA arbitration and exact refill latency are not modeled.
 ## Mixing and timing ownership
 
 Each routed Direct Sound sample contributes `sample * 2` at 50% volume or `sample * 4` at 100% volume.
-Pulse channel 1 contributes a centered signed amplitude, `+volume` or `-volume`, while active.
-`SOUNDCNT_L` routes it independently left/right and multiplies each side by its volume field plus one.
-`SOUNDCNT_H` then applies the PSG ratio: 25%, 50%, or 100%, using an arithmetic right shift.
-At full volume, channel 1 therefore spans `-120..120` before mixing with Direct Sound.
+Each active pulse contributes a centered signed amplitude, `+volume` or `-volume`.
+`SOUNDCNT_L` routes channel 1 through bits 8/12 and channel 2 through bits 9/13, for right/left respectively.
+The mixer sums routed PSG amplitudes on each side, then multiplies by that side's volume field plus one.
+`SOUNDCNT_H` applies the PSG ratio: 25%, 50%, or 100%, using one arithmetic right shift after summation.
+Rounding each pulse separately would produce different low-volume levels and is not used.
+At full volume, each pulse spans `-120..120` before mixing with Direct Sound.
 This centered mixer follows GBATEK's signed range and the NanoBoyAdvance comparison; exact analog offset is not modeled.
 The mixer adds all supported channels and the ten-bit bias, clips each side to `0..1023`, and subtracts 512.
 `StereoLevel` therefore contains signed levels in `-512..511`. Master disable returns zero.
@@ -144,16 +154,19 @@ They also cover cascaded timers, DMA block/repeat behavior, source progress, com
 CPU/DMA failure tests verify transactional rollback and sound writes at bus completion.
 BIOS tests cover disabled FIFO reset and the supported wave-bank policy.
 Pulse tests cover every frequency/duty pair, waveform batching, status, length, envelope, sweep, mixing, and reserved-volume diagnostics.
-They also check bus-completion status reads, retrigger timing, clock ownership, and rollback with a running pulse channel.
+They also check bus-completion status reads, retrigger timing, clock ownership, and rollback with both pulse channels running.
+Channel 2 tests cover register gaps, absence of sweep, independent state, shared sequencer phase, and sum-before-rounding mixing.
+Original CPU/DMA tests verify channel 2 activation and rollback when a later block-store value is unsupported.
+BIOS reset tests verify that selected sound reset stops both channels, while unselected sound state remains active.
 
 These tests validate the documented nominal model, not hardware audio fidelity.
-Next work: PSG channels 2–4, a timestamped or fixed-rate output stream, PWM/mixer sampling, and a Darwin host backend.
-The local Emerald startup now passes the channel 1 trigger and stops at a channel 2 trigger.
+Next work: noise channel 4, wave channel 3, a timestamped or fixed-rate output stream, PWM/mixer sampling, and a Darwin host backend.
+The local Emerald startup now passes both pulse triggers and stops at a noise channel 4 trigger.
 See [the local runtime result](../research/emerald-reset.md).
 
 ## References
 
-- [GBATEK channel 1](https://mgba-emu.github.io/gbatek/): register fields, duty ratios, and modulation rates.
+- [GBATEK channels 1 and 2](https://mgba-emu.github.io/gbatek/): register fields, duty ratios, modulation rates, channel 2's register gap, and absence of sweep.
 - [Pan Docs audio details](https://gbdev.io/pandocs/Audio_details.html): duty counters, shadow sweep, length edge rules, and GBA digital-mixer differences. GB-only edge details are not treated as verified GBA measurements.
 - [GbdevWiki sound hardware](https://gbdev.gg8.se/wiki/articles/Gameboy_sound_hardware): background sequencer and sweep descriptions.
 - [mGBA shared PSG at 3a5e34be](https://github.com/mgba-emu/mgba/blob/3a5e34be33dc7f8f707e5bc9db69e8a430046f21/src/gb/audio.c): GBA-style sequencer, length, envelope, sweep, and waveform comparison.

docs/hardware/bios.md

@@ -220,7 +220,7 @@ Supported flags can be combined:
 | 7 | Reset supported display, DMA, timer, and interrupt registers as described below |
 
 All low-byte flag combinations, including `r0=0xff`, are accepted within the supported device subset.
-This is not full audio or serial support. [PSG channels 2–4](audio.md) and [serial transfers](serial.md) still fail explicitly.
+This is not full audio or serial support. [PSG channels 3–4](audio.md) and [serial transfers](serial.md) still fail explicitly.
 Sound reset retains wave bank 0 and the separate in-flight playback word; exact firmware sound-reset equivalence is not established.
 The firmware always clears the low halfword of SIODATA32, even when bit 5 is clear; its upper halfword is preserved.
 
@@ -233,7 +233,7 @@ After the RAM clears, bit 5 clears SIOCNT and SIODATA8, writes RCNT=0x8000, and
 Disconnected general-purpose inputs read high, so RCNT reads back as 0x800f.
 Bit 6 disables SOUNDCNT_X, strobes both FIFO resets, clears SOUNDCNT_H, and sets SOUNDBIAS=0x0200.
 It then clears accessible wave bank 1. Wave bank 0 is retained and can be selected again after master enable.
-Disabled PSG registers remain zero. A running pulse channel stops only when sound reset is selected.
+Disabled PSG registers remain zero. Running pulse channels stop only when sound reset is selected.
 Reset does not produce audio, fabricate serial transfers, or bypass normal bus accesses.
 
 Bit 7 runs after the selected RAM and sound/serial resets:
@@ -511,5 +511,5 @@ Unsupported SWIs, unsupported exception vectors, and null/misaligned IRQ callbac
 The CPU reports `CpuError::UnsupportedInstruction` with `bios::UNSUPPORTED_TRAP`, rather than silently treating a service as a no-op.
 Invalid arithmetic/decompression arguments use the same CPU error type with the distinct `bios::INVALID_ARGUMENT_TRAP` instruction.
 Prior boot/service steps remain committed on failure.
-PSG channels 2–4, host audio output, serial transfers, HardReset, and serial/Game Pak STOP wake-up remain unimplemented.
+PSG channels 3–4, host audio output, serial transfers, HardReset, and serial/Game Pak STOP wake-up remain unimplemented.
 This subset is not sufficient for Pokémon Emerald compatibility.

docs/hardware/timers-irq.md

@@ -39,7 +39,7 @@ Failed steps discard staged counters, divider progress, timer/audio writes, FIFO
 Display and other device clocks then advance once, without advancing timers again.
 Display and remaining devices still use the bulk scheduler. Mid-instruction display events, general bus arbitration, and IRQ synchronization delays remain unmodeled.
 [Direct Sound](audio.md) consumes selected timer overflows in the timer transaction; sound DMA requests commit at step boundaries.
-The same transaction advances the PSG oscillator and 512 Hz sequencer independently of the general-purpose timers.
+The same transaction advances both PSG pulse oscillators and their shared 512 Hz sequencer independently of the general-purpose timers.
 Host clock advances and HALT idle batches retain ordinary bulk timer advancement; STOP idle does not advance timers.
 
 The unchanged [prefetch cancellation probe](../research/prefetch-cancellation.md) now matches both published interval totals and actual timer samples.

docs/research/emerald-reset.md

@@ -10,7 +10,7 @@ No ROM bytes, extracted code, or assets were added to the repository.
 ## General correction
 
 The reset correction introduced bounded sound and [disconnected serial](../hardware/serial.md) initialization models.
-The [sound model](../hardware/audio.md) now also supports Direct Sound, bounded FIFO DMA, and nominal pulse channel 1 playback.
+The [sound model](../hardware/audio.md) now also supports Direct Sound, bounded FIFO DMA, and both nominal pulse channels.
 The BIOS performs reset through original ARM stores against that model.
 Bit 5 selects general-purpose input pins and clears supported serial reset registers.
 Bit 6 disables sound, resets FIFO queues, clears mixing configuration and accessible wave RAM, and sets the functional bias default.
@@ -31,18 +31,18 @@ direnv exec . cargo run --locked --release -- --rom roms/pokemon-emerald.gba --w
 
 The earlier reset-only implementation stopped at master sound enable (`0x04000084`, PC `0x082e0518`).
 The Direct Sound increment then reached a PSG channel 1 trigger (`0x04000065`, PC `0x082e03bc`).
-After implementing channel 1, both runs pass that trigger and stop at channel 2:
+Channel 1 support reached the channel 2 trigger (`0x0400006d`, PC `0x082e03c0`).
+With both pulse channels implemented, both runs now stop at noise channel 4:
 
 ```text
-Steps: 321161; instructions: 320649; IRQ entries: 0; DMA units: 512; HALT idle: 0
-Nominal cycles: 1038742
-PC=0x082e03c0
-unsupported PSG channel trigger (synthesis not implemented): write 0x80 at 0x0400006d
+Steps: 321163; instructions: 320651; IRQ entries: 0; DMA units: 512; HALT idle: 0
+Nominal cycles: 1038746
+PC=0x082e03c4
+unsupported PSG channel trigger (synthesis not implemented): write 0x80 at 0x0400007d
 ```
 
-The native run captures three startup frames. Audio-device behavior is validated by original tests, not by audible game output.
-
-The native run captures startup frames before this diagnostic. These are not evidence of a working title screen or gameplay.
+The native run captures three startup frames. These do not establish a working title screen or gameplay.
+Audio-device behavior is validated by original tests, not by audible game output.
 The window run does not reach its requested frame limit and correctly exits with failure.
 Terminal execution is also diagnostic, not a compatibility pass.
 Results apply to this local file; no cartridge revision or checksum was inferred from its filename.
@@ -53,9 +53,10 @@ Workspace debug/release tests, strict Clippy, public ARM/Thumb/memory/BIOS check
 Native ROM-window tests and graphics smoke modes pass on Darwin arm64.
 The pinned Pong debug/release reports match.
 
-The next observed startup requirement is PSG pulse channel 2, which has no sweep unit.
-Channel 1 now has nominal waveform, length, envelope, sweep, and stereo mixing behavior.
-Direct Sound has FIFO clocks and nominal DMA requests. Both use the instantaneous digital-level inspection interface.
+The next observed startup requirement is noise channel 4. Wave channel 3 is also still missing.
+Both pulse channels now have independent nominal waveform, length, envelope, status, and stereo mixing behavior.
+Sweep applies only to channel 1. The two pulses share the sequencer without sharing their channel state.
+Direct Sound has FIFO clocks and nominal DMA requests. All supported channels use the instantaneous digital-level inspection interface.
 A continuous sample stream and desktop output are still missing. Do not treat digital-level tests as audible-game validation.
 Do not suppress the PSG trigger diagnostic without implementing the requested device behavior.
 Cartridge saves remain a separate required feature. SRAM alone will not support Emerald's Flash save protocol.

docs/status.md

@@ -79,8 +79,8 @@ Update this file when a feature lands or a limit is removed.
 - Firmware boot initializes BG2/BG3 identity scales for bitmap and affine programs that do not program their own matrices.
 - RegisterRamReset supports disabled sound and disconnected serial initialization, including the common `r0=0xff` request.
 - Direct Sound A/B support timer-driven FIFO playback, stereo digital levels, and DMA1/A or DMA2/B refill blocks.
-- PSG pulse channel 1 supports nominal frequency/duty playback, length, envelope, sweep, status, and stereo mixing.
-- Channels 2–4 triggers and unsupported serial operations produce explicit address/value diagnostics with whole-access and block-store rollback.
+- PSG pulse channels 1 and 2 support independent nominal frequency/duty playback, length, envelope, status, and stereo mixing. Channel 1 also supports sweep.
+- Channel 3–4 triggers and unsupported serial operations produce explicit address/value diagnostics with whole-access and block-store rollback.
 - ROM windows with scanline capture, keyboard input, focus-loss release, bounded execution slices, and interactive keypad wake from STOP.
 - Optional ROM-window frame limits and an original input-test ROM generator.
 - Headless JSON ROM suites with PC or VBlank completion, register/CPSR/memory/pixel assertions, scheduled buttons, bounded budgets, and structured failure reports.
@@ -137,8 +137,8 @@ Horizontal window comparators retain four-cycle event history.
 Sprite rows prepare one line ahead with a whole-row cycle40 sample and nominal per-row work limits.
 Individual fetch timing, hardware-accurate work cutoffs, video-bus contention, and per-pixel color composition remain unimplemented.
 There is no host audio output or cartridge save support.
-The [audio subset](hardware/audio.md) supports Direct Sound, PSG pulse channel 1, idle channel 2–4 state, wave banking, and instantaneous digital mixing.
-It does not yet provide a continuous sample stream. Channel 2–4 playback and unverified sound-DMA pairings remain diagnostic.
+The [audio subset](hardware/audio.md) supports Direct Sound, both PSG pulse channels, idle channel 3–4 state, wave banking, and instantaneous digital mixing.
+It does not yet provide a continuous sample stream. Channel 3–4 playback and unverified sound-DMA pairings remain diagnostic.
 PSG timing and signed mixing are nominal; hardware startup edges and analog behavior remain unverified.
 The [serial initialization subset](hardware/serial.md) supports idle normal data and disconnected general-purpose pins, not active transfers.
 Mapped I/O covers DMA, timers, interrupts, WAITCNT, display control/status, background control/scroll/affine registers, window/effect registers, KEYINPUT/KEYCNT, POSTFLG, and HALTCNT.
@@ -150,7 +150,7 @@ ROM files can run in bounded terminal mode or a window with the original BIOS re
 ROM windows have no demo-specific startup checks. Input is sampled between bounded execution slices.
 Audio, saves, and external BIOS loading remain unavailable. ROM loading does not establish commercial-game compatibility.
 A local Emerald run now completes its all-device reset and master sound enable.
-It also passes the channel 1 trigger, then stops explicitly at channel 2 (`0x0400006d`).
+It also passes both pulse triggers, then stops explicitly at noise channel 4 (`0x0400007d`).
 No title-screen, gameplay, or audible-game compatibility is established.
 Its captured startup frames do not establish title-screen or gameplay compatibility. See [the startup result](research/emerald-reset.md).
 See [cartridge loading](hardware/cartridge.md) for file limits, step budgets, and exit status.

docs/usability-roadmap.md

@@ -39,8 +39,9 @@ The [pinned Pong homebrew](public-pong.md) passes scripted menus, ball movement,
 The native Darwin window also starts and presents frames without a diagnostic.
 This exposed and corrected missing firmware affine-scale initialization, without a game-specific patch.
 Frame-based scenarios and the preparation adapter now make the result repeatable.
-A local Emerald run now passes its initial all-device reset, master sound enable, and PSG channel 1 trigger.
-It stops at a channel 2 trigger. The core has tested Direct Sound and pulse channel 1 behavior, but no continuous sample stream or desktop audio output.
+A local Emerald run now passes its initial all-device reset, master sound enable, and both PSG pulse triggers.
+It stops at a noise channel 4 trigger. The core has tested Direct Sound and both pulse channels.
+A continuous sample stream and desktop audio output remain missing.
 See [the runtime result](research/emerald-reset.md). Remaining PSG channels are the next demonstrated startup requirement.
 The separate save requirement remains cartridge SRAM, followed by safe host save persistence.
 SRAM is byte-addressable battery-backed save memory. Flash and EEPROM remain separate protocols.