gameframe-ymz263

A clean, timestamped model of Yamaha's YMZ263B (MMA) used in the AdLib Gold/GSS card. It models the two PCM/ADPCM FIFOs, sample-rate dividers, register ports, timer counters, DMA request conditions, MIDI FIFOs and UART transmit timing. The card-level adapter is in gameframe-adlib-gold.

Use it

[dependencies]
gameframe-ymz263 = { git = "https://github.com/tanepiper/game-frame" }

use gameframe_ymz263::Ymz263;

let mut mma = Ymz263::new();
mma.write_port_at(0, 0x0c, 0).unwrap(); // select channel 0 format/control
mma.write_port_at(1, 0x19, 8).unwrap(); // FIFO threshold 16 bytes, DMA enabled
mma.write_port_at(0, 0x0b, 16).unwrap(); // select channel 0 PCM data
for byte in 0..128 {
    mma.write_port_at(1, 0x80, 24 + byte * 8).unwrap(); // fill the FIFO before playback
}
mma.write_port_at(0, 0x09, 1_048).unwrap(); // select channel 0 playback control
mma.write_port_at(1, 0x65, 1_056).unwrap(); // PCM, GO, left and right outputs
mma.advance_to(2_000).unwrap();
let _samples = mma.drain_output_events();

Pass monotonically increasing YMZ263B master-clock timestamps. Port accesses enforce the minimum eight-clock interval derived from the toolkit's 470 ns timing. The four relative ports model the two index/data pairs used by the original GSS Windows driver. PCM output events preserve each channel's signed 12-bit sample, volume register and left/right routing bits. The host card model can consume those events and apply the card mixer.

Evidence and modeled behavior

The register map and supported modes follow Ad Lib's Developer Toolkit v1.01, Hardware Reference 4.3, and Yamaha's YMZ263B data sheet. The GSS.DRV v1.01 Windows NE driver confirms writes to two index/data pairs at offsets 0/1 and 2/3, use of registers 0x09, 0x0c and 0x0d, and timer setup through registers 0x02–0x08. The driver file and Ghidra output remain outside this repository. No emulator source code was consulted.

Implemented behavior:

• Separate 128-byte channel FIFOs and channel register state.
• Signed 8-bit and signed 12-bit PCM byte layouts, PCM and ADPCM sample cadence, play/record direction, stereo route bits, volume values and reset/start control.
• FIFO threshold status and DMA request conditions from register 0x0c.
• Channel 0 controlled alternating interleave mode, enabled only when both channels have DMA enabled, plus the documented shared playback/record mode and rate controls.
• Timer zero, base counter, timer one and timer two counters with their documented register locations and 32-master-clock counter units.
• Separate 16-byte MIDI transmit and receive FIFOs, reset controls used by the original driver, and serial output at 31,250 baud with fractional clock carry.
• The status byte's overrun, timer, MIDI request and FIFO threshold bits. Register 0x0d mask bits gate IRQ output without changing status, as the toolkit specifies.
• Timestamped port access, sample updates, MIDI output and external record-input injection.
• cargo test -p gameframe-ymz263 checks both 12-bit layouts, signed 8-bit PCM, ADPCM nibble order, FIFO thresholds, timer and MIDI timing. These checks exercise the implementation; the YMZ263B-specific ADPCM rounding still needs a software reference comparison.

Limits and software checks

This is a documented digital model, not a claim of complete silicon parity. YMZ263-specific ADPCM predictor clipping and rounding are inferred from Yamaha's related Y8950 algorithm. The toolkit does not specify exact timer-flag clear behavior, standby clock reduction or game-port electrical timing. Interleave and FIFO threshold behavior follow the toolkit description but need comparison against a software-instrumented driver. A run of the original GSS driver in an instrumented NE emulator can settle those points. Software checks can cover all FIFO sizes, formats, rates, timer reloads, MIDI reset and transfer sequences, driver port ordering and monotonic timestamp boundaries without a physical card.

The crate provides DMA request state but does not emulate a PC DMA controller, interrupt controller, analog ADC/DAC filters, card mixer, joystick RC circuit or telephone/microphone input path. Those belong to the machine or card layer. Real hardware testing is not required to make progress.

Licence

Apache 2.0.