feat(audio): implement PSG noise channel 4

docs/architecture.md

@@ -56,6 +56,9 @@ The repository is a Cargo workspace with three crates:
 | `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` | Shared pulse oscillator; sweep is mapped only for channel 1 |
 | `crates/gba-core/src/audio/modulation.rs` | Shared PSG length, envelope, logical DAC gate, and activity state |
+| `crates/gba-core/src/audio/noise.rs` | Noise channel 4 divider, 7/15-bit counter, and bounded jump-ahead advancement |
+| `crates/gba-core/src/audio/noise/tests.rs` | Counter periods, independent bit-array reference, divider fields, and clock batching |
+| `crates/gba-core/tests/noise_sound.rs` | Noise registers, modulation, stereo mixing, independent status, HALT/STOP, and capture independence |
 | `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 |

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 channels 1 and 2.
-It does not produce desktop audio. PSG wave channel 3 and noise channel 4 remain unsupported.
+The core models Direct Sound A/B, bounded sound DMA, and programmable sound generator (PSG) pulse channels 1–2 and noise channel 4.
+It does not produce desktop audio. PSG wave channel 3 remains unsupported.
 `Memory::audio_level()` exposes the current digital stereo level for deterministic inspection, not a continuous sample stream.
 
 ## Registers and PSG state
@@ -11,9 +11,12 @@ It does not produce desktop audio. PSG wave channel 3 and noise channel 4 remain
 | `0x04000060..0x04000065` | Pulse channel 1 sweep, duty, length, envelope, frequency, and trigger |
 | `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 |
+| `0x04000070..0x04000075` | Idle wave channel 3 configuration |
+| `0x04000078..0x04000079` | Noise channel 4 length and envelope |
+| `0x0400007c..0x0400007d` | Noise divider, counter width, shift, length enable, and trigger |
+| `0x04000080..0x04000081` | PSG stereo routing and volume |
 | `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/2 activity in bits 0/1; channels 3–4 remain inactive |
+| `0x04000084` (`SOUNDCNT_X`) | Master enable in bit 7; channel 1/2/4 activity in read-only bits 0/1/3; channel 3 remains 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 |
@@ -28,10 +31,10 @@ 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 3–4 trigger returns `MemoryError::UnsupportedIo` with the exact address and value.
+An enabled wave channel 3 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 3–4 writes do not imply playback support.
+Idle wave channel 3 writes do not imply playback support.
 
 ## Pulse channels 1 and 2
 
@@ -84,6 +87,41 @@ First-trigger output suppression, trigger sub-divider alignment, envelope trigge
 The model samples the selected duty position immediately after trigger and uses a full-period timer reload.
 The consulted implementations differ on some initial phases and envelope/sweep edge cases; no GBA hardware audio recording was used as an oracle.
 
+## Noise channel 4
+
+Noise uses a deterministic linear-feedback shift register (LFSR), not a host random-number generator.
+The nominal counter follows GBATEK's GBA Galois description:
+
+| Width | Trigger seed | Feedback mask | Sequence period |
+| --- | --- | --- | --- |
+| 15-bit | `0x4000` | `0x6000` | 32767 shifts |
+| 7-bit | `0x0040` | `0x0060` | 127 shifts |
+
+At each edge, the old low bit selects the signed output level.
+The counter shifts right and, when that bit was one, XORs the feedback mask.
+The period between edges is `(ratio == 0 ? 32 : 64 * ratio) << shift` system clocks.
+All eight divider fields and sixteen shift fields use this GBA formula, including shifts 14 and 15.
+No general-purpose timer or IRQ enable is required.
+
+A trigger reloads the selected seed, full edge interval, envelope, and applicable length state.
+The nominal held output starts low and changes at counter edges.
+Live divider/shift writes preserve the remaining interval; the new period applies on the next reload.
+Live width writes preserve the full counter, including transient upper bits, and select the new feedback mask.
+They do not truncate or reseed the counter.
+Exact hardware startup alignment and live-width transition behavior remain unverified.
+The consulted mGBA implementation uses a different counter representation; this model does not claim matching initial sample phases.
+
+Length, envelope, logical DAC gating, and activity use the same tested modulation implementation as the pulse channels.
+All three channels receive the shared sequencer clocks but keep independent state.
+Noise status uses SOUNDCNT_X bit 3. Envelope saturation alone does not clear it.
+Master disable resets noise configuration and counter state. Muting its routing does not stop it.
+The unused halfwords at `0x0400007a` and `0x0400007e` read zero and do not alias noise controls.
+
+Large clock advances combine precomputed powers of the counter transition instead of shifting once per noise sample.
+An independent bit-array reference checks these jump-ahead operations, including live-width transients and the final output carry.
+Both complete sequence periods and maximum clock batches have deterministic regressions.
+This is device-state advancement, not a sampled audio stream or hardware recording comparison.
+
 ## FIFO and timer behavior
 
 Each channel has a seven-word queue, a separate four-byte playback word, and a held signed sample.
@@ -128,12 +166,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.
-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.
+Each active pulse or noise channel contributes a centered signed amplitude, `+volume` or `-volume`.
+`SOUNDCNT_L` routes channel 1 through bits 8/12, channel 2 through bits 9/13, and noise through bits 11/15, 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.
+Rounding each PSG channel separately would produce different low-volume levels and is not used.
+At full volume, each supported PSG channel 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.
@@ -157,15 +195,20 @@ Pulse tests cover every frequency/duty pair, waveform batching, status, length,
 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.
+Noise tests cover both counter widths, divider/shift fields, complete sequences, jump-ahead arithmetic, retrigger, and live rate/width writes.
+They also cover modulation, independent status, stereo mixing, HALT/STOP, and scanline-capture independence.
+CPU/DMA tests include noise register writes at bus completion and failed-step rollback with a running counter.
+BIOS reset tests verify that selected sound reset stops all supported PSG channels, while unselected sound state remains active.
 
 These tests validate the documented nominal model, not hardware audio fidelity.
-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.
+Remaining audio work: wave channel 3, a timestamped or fixed-rate output stream, PWM/mixer sampling, and a Darwin host backend.
+The local Emerald startup now passes the pulse and noise triggers, then stops at GPIO serial interrupt control.
 See [the local runtime result](../research/emerald-reset.md).
 
 ## References
 
+- [GBATEK noise channel 4](https://mgba-emu.github.io/gbatek/): length/envelope registers, divider formula, Galois counter seeds, masks, and sequence periods.
+- [NanoBoyAdvance noise at 55b5cf0a](https://github.com/nba-emu/NanoBoyAdvance/blob/55b5cf0ae3d929582ac5bfd486558173502b8354/src/nba/src/hw/apu/channel/noise_channel.cc) and [noise header](https://github.com/nba-emu/NanoBoyAdvance/blob/55b5cf0ae3d929582ac5bfd486558173502b8354/src/nba/src/hw/apu/channel/noise_channel.hh): GBA divider scaling, counter feedback, trigger, and register behavior comparison.
 - [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.

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 3–4](audio.md) and [serial transfers](serial.md) still fail explicitly.
+This is not full audio or serial support. [wave channel 3](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. Running pulse channels stop only when sound reset is selected.
+Disabled PSG registers remain zero. Running pulse and noise 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 3–4, host audio output, serial transfers, HardReset, and serial/Game Pak STOP wake-up remain unimplemented.
+PSG wave channel 3, 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 both PSG pulse oscillators and their shared 512 Hz sequencer independently of the general-purpose timers.
+The same transaction advances both PSG pulse oscillators, the noise counter, 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 both nominal pulse channels.
+The [sound model](../hardware/audio.md) now also supports Direct Sound, bounded FIFO DMA, both pulse channels, and noise channel 4.
 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.
@@ -32,16 +32,17 @@ 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`).
 Channel 1 support reached the channel 2 trigger (`0x0400006d`, PC `0x082e03c0`).
-With both pulse channels implemented, both runs now stop at noise channel 4:
+Both pulse channels then reached the noise trigger (`0x0400007d`, PC `0x082e03c4`).
+With noise channel 4 implemented, both runs now stop at general-purpose input/output (GPIO) serial interrupt enable:
 
 ```text
-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
+Steps: 395420; instructions: 393690; IRQ entries: 2; DMA units: 1728; HALT idle: 0
+Nominal cycles: 1328057
+PC=0x082e2aac
+unsupported GPIO serial interrupt enable: write 0x01 at 0x04000135
 ```
 
-The native run captures three startup frames. These do not establish a working title screen or gameplay.
+The native run captures five 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.
@@ -53,12 +54,15 @@ 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 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.
+The next observed requirement is [serial control-register behavior](../hardware/serial.md), specifically RCNT bit 8.
+Check mode gating and interrupt-enable semantics before changing the current rejection.
+This diagnostic alone does not establish that the game needs an active link transfer.
+
+Noise now has deterministic counter clocks and shares tested length/envelope logic with the independent pulse channels.
+Sweep applies only to channel 1. Direct Sound has FIFO clocks and nominal DMA requests.
+All supported channels use the instantaneous digital-level inspection interface.
+Wave channel 3, a continuous sample stream, and desktop output are still missing.
+Do not treat digital-level tests as audible-game validation or suppress remaining diagnostics without implementing their behavior.
 Cartridge saves remain a separate required feature. SRAM alone will not support Emerald's Flash save protocol.
 
 Hardware and emulator references are recorded in the linked subsystem documents.

docs/status.md

@@ -80,7 +80,8 @@ Update this file when a feature lands or a limit is removed.
 - 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 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.
+- Noise channel 4 supports nominal 7/15-bit generation, divider clocks, shared length/envelope behavior, status, and stereo mixing.
+- Wave channel 3 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 +138,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, 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.
+The [audio subset](hardware/audio.md) supports Direct Sound, both PSG pulse channels, noise channel 4, idle wave channel 3 state, and instantaneous digital mixing.
+It does not yet provide a continuous sample stream. Wave channel 3 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 +151,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 both pulse triggers, then stops explicitly at noise channel 4 (`0x0400007d`).
+It also passes the pulse and noise triggers, then stops explicitly at GPIO serial interrupt enable (`0x04000135`).
 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,10 +39,10 @@ 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 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.
+A local Emerald run now passes its initial all-device reset, master sound enable, and pulse/noise triggers.
+It stops at GPIO serial interrupt control. The core has tested Direct Sound, both pulse channels, and noise channel 4.
+Wave channel 3, a continuous sample stream, and desktop audio output remain missing.
+See [the runtime result](research/emerald-reset.md). Serial control-register semantics 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.