Gravis UltraSound emulation

[Copilot]

Description of Changes

Adds Gravis Ultrasound sound card emulation to spice86.

Rationale Behind Changes

The Gravis UltraSound (GUS) sound card is used by real-mode DOS games and demos. Spice86 had no GUS presence at all, causing programs that probe for it to fail or crash.

Suggested Testing Steps

• Run a DOS program or demo that auto-detects GUS (e.g. sets ULTRASND=240,7,7,5,5 and probes port 0x240). Confirm it no longer crashes or throws an unhandled I/O port exception.
• Confirm SoundBlaster and PC speaker audio are unaffected.

• Fixes Feature request: Gravis Ultrasound sound card emulation #319

[maximilien-noal]

@copilot I want the full gravis ultrasound, not a skeleton.

https://github.com/dosbox-staging/dosbox-staging see gus.cpp and related files

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

@copilot I want the full gravis ultrasound, not a skeleton.

https://github.com/dosbox-staging/dosbox-staging see gus.cpp and related files

Implemented the full GUS GF1 emulation in commit feat: implement full Gravis UltraSound GF1 emulation based on dosbox-staging reference, faithfully porting the dosbox-staging gus.cpp/gus.h logic to C#. Key changes:

Register protocol – port 0x304 byte-write now latches the low byte only; port 0x305 latches the high byte and commits the 16-bit register_data to the selected register, matching the real GF1 two-byte write sequence.

All GF1 registers – correct byte ordering (control/vol/pan use the high byte), volume start/end in EEEEMMMM format, wave address MSW/LSW with proper 13-bit masking, GetDmaOffset/UpdateDmaAddr for 16-bit DMA channel translation, and missing reads for registers 0x41, 0x42, 0x45, 0x4C, 0x82/83, 0x8A/8B.

Reset register (0x4C) – full GF1 reset when is_running=0; rendering is gated on is_running && is_dac_enabled.

Mix control / IRQ – latches_enabled (bit 3) gates IRQ activation; irq_control_selected (bit 6) steers port 0x20B between IRQ/DMA address selection using the GUS SDK lookup tables.

Voice IRQ – CheckVoiceIrqs sets irq_status bits 0x20/0x40 and advances voice_irq.Status to the next pending voice; register 0x8F returns the correct format with inverted vol/wave bits.

Timers – corrected base delays (80 µs / 320 µs), mask bit handling, ShouldRaiseIrq per timer, and precomputed delay on value write.

Lookup tables – vol scalars use the DELTA_DB = 0.002709201 constant-dB formula; pan scalars use the asymmetric normalisation that puts position 7 exactly at centre.

GusVoice – ReadCtrlState now checks the per-voice irqMask (not the fixed 0x80); RenderFrames skips only when both wave AND vol controls are simultaneously disabled.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

src/Spice86.Core/Emulator/Devices/Sound/GravisUltraSound.cs:701

• CheckVoiceIrqs sets IrqVolStateBit/IrqWaveStateBit based on the full _voiceIrq bitmasks, but totalMask is computed using activeVoiceMask. If a program raises IRQ bits on an inactive voice index (>= _activeVoices), the status byte can incorrectly report a pending wave/vol IRQ. Mask the individual wave/vol bitmasks before setting the status bits.

        if (_voiceIrq.VolState != 0) {
            _irqStatus |= IrqVolStateBit;
        }
        if (_voiceIrq.WaveState != 0) {
            _irqStatus |= IrqWaveStateBit;

src/Spice86.Core/Emulator/Devices/Sound/GusVoice.cs:77

• RenderFrames' early-return checks the intersection of CtrlDisabled bits across WaveState and VolState. If WaveState and VolState are both disabled but with different disabled bits set (e.g., Reset vs Stopped), rendering will incorrectly proceed. This should instead check each control state independently for any disabled bit.

    public void RenderFrames(byte[] ram, float[] volScalars, AudioFrame[] panScalars, AudioFrame[] frames, int count) {
        // Skip rendering only when BOTH wave AND vol controls are independently disabled,
        // matching the GF1 hardware behaviour documented in the UltraSound SDK.
        if ((WaveState & VolState & CtrlDisabled) != 0) {
            return;

src/Spice86.Core/Emulator/Devices/Sound/GravisUltraSound.cs:193

• This PR adds a new hardware device with a non-trivial port map, IRQ, and DMA behavior, but there are no integration tests validating GUS detection/probing or basic IRQ/DMA flows. There is already a sound integration test suite (e.g., SoundIntegrationTests) for SoundBlaster; a similar test that runs a small COM fixture which probes 0x240 and/or checks ULTRASND-related behavior would help prevent regressions and ensure the original crash scenario is covered.

        InitPortHandlers(ioPortDispatcher, portBase);

        // Mixer setup
        mixer.RegisterQueueNotifier(this);
        mixer.LockMixerThread();