SID.java
/**
* This file is part of reSID, a MOS6581 SID emulator engine.
* Copyright (C) 2004 Dag Lem <resid@nimrod.no>
* <p>
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License or
* (at your option) any later version.
* <p>
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
* <p>
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* @author Ken Händel
*
*/
package builder.resid.resid;
import libsidplay.common.ChipModel;
import libsidplay.common.Potentiometer;
import libsidplay.common.SIDChip;
import libsidplay.config.IFilterSection;
import java.util.function.IntConsumer;
/**
* MOS6581/MOS8580 emulation. Based on reSID 1.0beta by Dag Lem, ported to Java
* by Antti S. Lankila. Slight changes by Ken händel.
*
* @author Ken Händel
* @author Dag Lem
* @author Antti Lankila
*/
public final class SID implements SIDChip {
private static final int INPUTDIGIBOOST = 0x3FF;
private static final int NO_INPUTDIGIBOOST = 0x07F;
/**
* Output scaler.
*/
private static final int OUTPUT_LEVEL = 359;
/**
* SID voices
*/
public final Voice[] voice = new Voice[]{new Voice(), new Voice(), new Voice()};
/**
* Currently active filter
*/
private Filter filter;
/**
* Filter used if the model is set to 6581
*/
private final Filter6581 filter6581 = new Filter6581();
/**
* Filter used if the model is set to 8580
*/
private final Filter8580 filter8580 = new Filter8580();
private double dacNonlinearity6581 = 2.2, dacNonlinearity8580 = 2.0;
/**
* External filter that provides high-pass and low-pass filtering to adjust
* sound tone slightly.
*/
private final ExternalFilter externalFilter = new ExternalFilter();
/**
* Paddle X register support
*/
private final Potentiometer potX = new Potentiometer() {
};
/**
* Paddle Y register support
*/
private final Potentiometer potY = new Potentiometer() {
};
/**
* Last written value
*/
private byte busValue;
/**
* Time to live for the last written value
*/
private int busValueTtl, databus_ttl, write_address;
/**
* Currently active chip model.
*/
private ChipModel model;
/**
* Time until synchronize() must be run.
*/
private int nextVoiceSync;
private final boolean[] muted = new boolean[4];
/**
* Estimate DAC nonlinearity. The SID contains R-2R ladder, and some likely
* errors in the resistor lengths that result in errors depending on the bits
* chosen.
* <p>
* This model was derived by Dag Lem, and is port of the upcoming reSID version.
* On average, it shows a value higher than the target by a value that depends
* on the _2R_div_R parameter. It differs from the version written by Antti
* Lankila chiefly in the emulation of the lacking termination of the 2R ladder,
* which destroys the output with respect to the low bits of the DAC.
* <p>
* Returns the analog value as modeled from the R-2R network.
*
* @param dac digital value to convert to analog
* @param _2R_div_R resistor ratio, 2.0 for an ideal terminated R-2R DAC.
* @param term is the dac terminated by a 2R resistor? (6581 DACs are not)
*/
static void kinkedDac(final double[] dac, final double _2R_div_R, final boolean term) {
final double INFINITY = 1e6;
// Calculate voltage contribution by each individual bit in the R-2R
// ladder.
for (int set_bit = 0; set_bit < dac.length; set_bit++) {
int bit;
double Vn = 1; // Normalized bit voltage.
double R = 1; // Normalized R
double _2R = _2R_div_R * R; // 2R
double Rn = term ? // Rn = 2R for correct termination,
_2R : INFINITY; // INFINITY for missing termination.
// Calculate DAC "tail" resistance by repeated parallel
// substitution.
for (bit = 0; bit < set_bit; bit++) {
if (Rn == INFINITY) {
Rn = R + _2R;
} else {
Rn = R + _2R * Rn / (_2R + Rn); // R + 2R || Rn
}
}
// Source transformation for the bit voltage.
if (Rn == INFINITY) {
Rn = _2R;
} else {
Rn = _2R * Rn / (_2R + Rn); // 2R || Rn
Vn = Vn * Rn / _2R;
}
// Calculate DAC output voltage by repeated source transformation
// from
// the "tail".
for (++bit; bit < dac.length; bit++) {
Rn += R;
double I = Vn / Rn;
Rn = _2R * Rn / (_2R + Rn); // 2R || Rn
Vn = Rn * I;
}
dac[set_bit] = Vn;
}
/* Normalize to integerish behavior */
double Vsum = 0;
for (double element : dac) {
Vsum += element;
}
Vsum /= 1 << dac.length;
for (int i = 0; i < dac.length; i++) {
dac[i] /= Vsum;
}
}
/**
* Constructor.
*/
public SID() {
reset();
setChipModel(ChipModel.MOS8580);
}
/**
* Set a chip model.
*
* @param model chip model to use
*/
@Override
public void setChipModel(final ChipModel model) {
this.model = model;
/**
* <pre>
* results from real C64 (testprogs/SID/bitfade/delayfrq0.prg):
*
* (new SID) (250469/8580R5) (250469/8580R5)
* delayfrq0 ~7a000 ~108000
*
* (old SID) (250407/6581)
* delayfrq0 ~01d00
*
* </pre>
**/
databus_ttl = model == ChipModel.MOS8580 ? 0xa2000 : 0x1d00;
if (model == ChipModel.MOS6581) {
filter = filter6581;
} else if (model == ChipModel.MOS8580) {
filter = filter8580;
} else {
throw new RuntimeException("Don't know how to handle chip type " + model);
}
/* calculate waveform-related tables, feed them to the generator */
final short[][] tables = WaveformCalculator.buildTable(model);
/* update voice offsets */
for (int i = 0; i < 3; i++) {
voice[i].envelope.setChipModel(model);
voice[i].wave.setChipModel(model);
voice[i].wave.setWaveformModels(tables);
}
double ratio = model == ChipModel.MOS6581 ? dacNonlinearity6581 : dacNonlinearity8580;
if (ratio != (model == ChipModel.MOS6581 ? 2.2 : 2.0)) updateVoiceDacs(ratio);
}
/** Preset calibration; the native defaults preserve the historical output. */
public void configureFilter(IFilterSection settings) {
checkedDacRatio(settings.getVoiceNonlinearity());
filter.setResonanceFactor(settings.getResonanceFactor());
setDacNonlinearity(settings.getVoiceNonlinearity());
if (model == ChipModel.MOS6581) filter6581.setFilterCurve(settings.getFilter6581CurvePosition());
else filter8580.setFilterCurve(settings.getFilter8580CurvePosition());
}
static double checkedDacRatio(float ratio) {
// Use the nominal double upper bound for direct JavaScript calls at exactly 2.6.
if (!Float.isFinite(ratio) || ratio < 1.8f || ratio > 2.6)
throw new IllegalArgumentException("ReSID DAC resistor ratio must be 1.8..2.6");
// Preserve the original double-precision default after INI/JSON float conversion.
return ratio == 2.2f ? 2.2 : (double) ratio;
}
public float getDacNonlinearity() {
return (float) (model == ChipModel.MOS6581 ? dacNonlinearity6581 : dacNonlinearity8580);
}
public void setDacNonlinearity(float ratio) {
double calibrated = checkedDacRatio(ratio);
if (calibrated == (model == ChipModel.MOS6581 ? dacNonlinearity6581 : dacNonlinearity8580)) return;
if (model == ChipModel.MOS6581) {
dacNonlinearity6581 = calibrated;
filter6581.setDacNonlinearity(ratio);
} else dacNonlinearity8580 = calibrated;
updateVoiceDacs(calibrated);
}
private void updateVoiceDacs(double ratio) {
for (Voice v : voice) {
v.wave.setDacNonlinearity(ratio);
v.envelope.setDacNonlinearity(model, ratio);
}
}
ChipModel getChipModel() {
return model;
}
/**
* SID reset.
*/
@Override
public void reset() {
for (int i = 0; i < 3; i++) {
voice[i].reset();
}
filter6581.reset();
filter8580.reset();
externalFilter.reset();
busValue = 0;
busValueTtl = 0;
write_address = 0;
voiceSync(false);
}
/**
* 16-bit input (EXT IN). Write a 16-bit sample to audio input. NB! The caller is
* responsible for keeping the value within 16 bits. Note that to mix in an
* external audio signal, the signal should be resampled to 1MHz first to avoid
* sampling noise.
*
* @param value input level to set
*/
@Override
public void input(final int value) {
filter6581.input(value);
filter8580.input(value);
}
/**
* Read a SID register or the retained internal bus value.
* <p>
* Inherited reSID bus model: readable registers drive the bus just as writes
* do, so OSC3 refreshes the value later seen at a write-only address. The
* chip-specific whole-byte lifetime and its halving on write-only reads
* approximate leakage; they do not simulate the decay of individual bits.
* SIDRegisterRegressionTest.oscReadRefreshesInternalBus checks this contract;
* the bitfade measurements cited in setChipModel() motivate the model times.
*
* @param offset SID register to read
* @return value read from chip
*/
@Override
public byte read(final int offset) {
switch (offset) {
case 0x19:
busValue = potX.readPOT();
busValueTtl = databus_ttl;
break;
case 0x1a:
busValue = potY.readPOT();
busValueTtl = databus_ttl;
break;
case 0x1b:
// OSC3 observes voice 3's latch; its ring partner is voice 2.
// Refreshing the internal bus must not advance oscillator time.
busValue = model == ChipModel.MOS6581 ? voice[2].wave.readOSC6581(voice[1].wave)
: voice[2].wave.readOSC8580(voice[1].wave);
busValueTtl = databus_ttl;
break;
case 0x1c:
busValue = voice[2].envelope.readENV();
busValueTtl = databus_ttl;
break;
default:
busValueTtl /= 2;
break;
}
return busValue;
}
/**
* Write registers.
*
* @param offset chip register to write
* @param value value to write
*/
@Override
public void write(final int offset, final byte value) {
write_address = offset;
busValue = value;
busValueTtl = databus_ttl;
switch (write_address) {
case 0x00:
voice[0].wave.writeFREQ_LO(busValue);
break;
case 0x01:
voice[0].wave.writeFREQ_HI(busValue);
break;
case 0x02:
voice[0].wave.writePW_LO(busValue);
break;
case 0x03:
voice[0].wave.writePW_HI(busValue);
break;
case 0x04:
voice[0].writeCONTROL_REG(muted[0] ? 0 : busValue);
break;
case 0x05:
voice[0].envelope.writeATTACK_DECAY(busValue);
break;
case 0x06:
voice[0].envelope.writeSUSTAIN_RELEASE(busValue);
break;
case 0x07:
voice[1].wave.writeFREQ_LO(busValue);
break;
case 0x08:
voice[1].wave.writeFREQ_HI(busValue);
break;
case 0x09:
voice[1].wave.writePW_LO(busValue);
break;
case 0x0a:
voice[1].wave.writePW_HI(busValue);
break;
case 0x0b:
voice[1].writeCONTROL_REG(muted[1] ? 0 : busValue);
break;
case 0x0c:
voice[1].envelope.writeATTACK_DECAY(busValue);
break;
case 0x0d:
voice[1].envelope.writeSUSTAIN_RELEASE(busValue);
break;
case 0x0e:
voice[2].wave.writeFREQ_LO(busValue);
break;
case 0x0f:
voice[2].wave.writeFREQ_HI(busValue);
break;
case 0x10:
voice[2].wave.writePW_LO(busValue);
break;
case 0x11:
voice[2].wave.writePW_HI(busValue);
break;
case 0x12:
voice[2].writeCONTROL_REG(muted[2] ? 0 : busValue);
break;
case 0x13:
voice[2].envelope.writeATTACK_DECAY(busValue);
break;
case 0x14:
voice[2].envelope.writeSUSTAIN_RELEASE(busValue);
break;
case 0x15:
filter6581.writeFC_LO(busValue);
filter8580.writeFC_LO(busValue);
break;
case 0x16:
filter6581.writeFC_HI(busValue);
filter8580.writeFC_HI(busValue);
break;
case 0x17:
filter6581.writeRES_FILT(busValue);
filter8580.writeRES_FILT(busValue);
break;
case 0x18:
// samples muted? Fade-in is allowed anyway
if (!muted[3] || (value & 0xf) >= filter6581.vol) {
filter6581.writeMODE_VOL(busValue);
filter8580.writeMODE_VOL(busValue);
}
break;
default:
break;
}
/* Update voicesync just in case. */
voiceSync(false);
}
/**
* SID voice muting.
*
* @param channel channel to modify
* @param mute is muted?
*/
@Override
public void mute(final int channel, final boolean mute) {
if (channel < 4) {
muted[channel] = mute;
}
}
/** Read-only presentation state; no clocking or register access. */
public int getMuteMask() {
return (muted[0] ? 1 : 0) | (muted[1] ? 2 : 0) | (muted[2] ? 4 : 0) | (muted[3] ? 8 : 0);
}
public boolean isDigiBoostEnabled() {
return model == ChipModel.MOS8580 && filter8580.getExternalInput() == (INPUTDIGIBOOST << 4);
}
/**
* Setting of clock frequency.
*
* @param clockFrequency System clock frequency at Hz
*/
@Override
public void setClockFrequency(final double clockFrequency) {
filter6581.setClockFrequency(clockFrequency);
filter8580.setClockFrequency(clockFrequency);
externalFilter.setClockFrequency(clockFrequency);
}
private void ageBusValue(final int n) {
if (busValueTtl != 0) {
busValueTtl -= n;
if (busValueTtl <= 0) {
busValue = 0;
busValueTtl = 0;
}
}
}
/**
* Clock SID forward using the chosen output sampling algorithm.
*
* @param cycles c64 clocks to clock
* @param sample sample consumer
*/
@Override
public void clock(int cycles, IntConsumer sample) {
ageBusValue(cycles);
while (cycles != 0) {
int delta_t = Math.min(nextVoiceSync, cycles);
if (delta_t > 0) {
for (int i = 0; i < delta_t; i++) {
sample.accept(clock() * OUTPUT_LEVEL >> 8);
}
filter.zeroDenormals();
externalFilter.zeroDenormals();
cycles -= delta_t;
nextVoiceSync -= delta_t;
}
if (nextVoiceSync == 0) {
voiceSync(true);
}
}
}
/**
* Advance one sample with independent voice slots. The optimized waveform
* path assumes exactly one clock and output per slot; manual/aliased calls
* must retain the literal latch and feedback behavior.
*/
private int clock() {
Voice first = voice[0], second = voice[1], third = voice[2];
if (first == second || second == third || third == first) return clockAliased(first, second, third);
first.wave.clockClocked();
second.wave.clockClocked();
third.wave.clockClocked();
first.envelope.clock();
second.envelope.clock();
third.envelope.clock();
// Ring inputs follow 1<-3, 2<-1, 3<-2, using the already-clocked phases.
// SIDWaveformTimingTest.ringModulationUsesVoiceTwoAndTheCorrectPolarity.
return externalFilter.clock(filter.clock(first.outputClocked(third.wave), second.outputClocked(first.wave),
third.outputClocked(second.wave)));
}
/**
* API compatibility for reused Voice objects, not a physical SID configuration.
* Each slot retains its historical clock/output side effects; see
* SIDWaveformAPITrace.traceAliasedNoiseBoundary.
*/
private int clockAliased(Voice first, Voice second, Voice third) {
first.wave.clock();
second.wave.clock();
third.wave.clock();
first.envelope.clock();
second.envelope.clock();
third.envelope.clock();
return externalFilter.clock(filter.clock(first.output(third.wave), second.output(first.wave),
third.output(second.wave)));
}
/**
* Apply due hard sync and schedule the next source MSB rise. This backend
* emits the boundary sample first; synchronizeAfterOutput() preserves its
* pulse/tri-saw latches before resetting phase. Register writes reschedule
* with sync=false, so a changed frequency does not itself trigger a reset.
*/
private void voiceSync(boolean sync) {
if (sync) {
/* Synchronize the 3 waveform generators. */
for (int i = 0; i < 3; i++) {
voice[i].wave.synchronizeAfterOutput(voice[(i + 1) % 3].wave, voice[(i + 2) % 3].wave);
}
}
/* Calculate the time to the next voice sync */
nextVoiceSync = Integer.MAX_VALUE;
for (int i = 0; i < 3; i++) {
int accumulator = voice[i].wave.accumulator;
int freq = voice[i].wave.freq;
if (voice[i].wave.test || freq == 0 || !voice[(i + 1) % 3].wave.sync) {
continue;
}
int thisVoiceSync = (0x7fffff - accumulator & 0xffffff) / freq + 1;
if (thisVoiceSync < nextVoiceSync) {
nextVoiceSync = thisVoiceSync;
}
}
}
/**
* Get chip's 6581 filter.
*
* @return filter
*/
public Filter6581 getFilter6581() {
return filter6581;
}
/**
* Get chip's 8580 filter.
*
* @return filter
*/
public Filter8580 getFilter8580() {
return filter8580;
}
@Override
public void setDigiBoost(boolean digiBoost) {
if (digiBoost && model.equals(ChipModel.MOS8580)) {
input(INPUTDIGIBOOST);
} else {
input(NO_INPUTDIGIBOOST);
}
}
}