libsidplayfp 1.0.3
wave.h
00001 //  ---------------------------------------------------------------------------
00002 //  This file is part of reSID, a MOS6581 SID emulator engine.
00003 //  Copyright (C) 2010  Dag Lem <resid@nimrod.no>
00004 //
00005 //  This program is free software; you can redistribute it and/or modify
00006 //  it under the terms of the GNU General Public License as published by
00007 //  the Free Software Foundation; either version 2 of the License, or
00008 //  (at your option) any later version.
00009 //
00010 //  This program is distributed in the hope that it will be useful,
00011 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
00012 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00013 //  GNU General Public License for more details.
00014 //
00015 //  You should have received a copy of the GNU General Public License
00016 //  along with this program; if not, write to the Free Software
00017 //  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00018 //  ---------------------------------------------------------------------------
00019 
00020 #ifndef RESID_WAVE_H
00021 #define RESID_WAVE_H
00022 
00023 #include "resid-config.h"
00024 
00025 namespace reSID
00026 {
00027 
00028 // ----------------------------------------------------------------------------
00029 // A 24 bit accumulator is the basis for waveform generation. FREQ is added to
00030 // the lower 16 bits of the accumulator each cycle.
00031 // The accumulator is set to zero when TEST is set, and starts counting
00032 // when TEST is cleared.
00033 // The noise waveform is taken from intermediate bits of a 23 bit shift
00034 // register. This register is clocked by bit 19 of the accumulator.
00035 // ----------------------------------------------------------------------------
00036 class WaveformGenerator
00037 {
00038 public:
00039   WaveformGenerator();
00040 
00041   void set_sync_source(WaveformGenerator*);
00042   void set_chip_model(chip_model model);
00043 
00044   void clock();
00045   void clock(cycle_count delta_t);
00046   void synchronize();
00047   void reset();
00048 
00049   void writeFREQ_LO(reg8);
00050   void writeFREQ_HI(reg8);
00051   void writePW_LO(reg8);
00052   void writePW_HI(reg8);
00053   void writeCONTROL_REG(reg8);
00054   reg8 readOSC();
00055 
00056   // 12-bit waveform output.
00057   short output();
00058 
00059   // Calculate and set waveform output value.
00060   void set_waveform_output();
00061   void set_waveform_output(cycle_count delta_t);
00062 
00063 protected:
00064   void clock_shift_register();
00065   void write_shift_register();
00066   void reset_shift_register();
00067   void set_noise_output();
00068 
00069   const WaveformGenerator* sync_source;
00070   WaveformGenerator* sync_dest;
00071 
00072   reg24 accumulator;
00073 
00074   // Tell whether the accumulator MSB was set high on this cycle.
00075   bool msb_rising;
00076 
00077   // Fout  = (Fn*Fclk/16777216)Hz
00078   // reg16 freq;
00079   reg24 freq;
00080   // PWout = (PWn/40.95)%
00081   reg12 pw;
00082 
00083   reg24 shift_register;
00084 
00085   // Remaining time to fully reset shift register.
00086   cycle_count shift_register_reset;
00087   // Emulation of pipeline causing bit 19 to clock the shift register.
00088   cycle_count shift_pipeline;
00089 
00090   // Helper variables for waveform table lookup.
00091   reg24 ring_msb_mask;
00092   unsigned short no_noise;
00093   unsigned short noise_output;
00094   unsigned short no_noise_or_noise_output;
00095   unsigned short no_pulse;
00096   unsigned short pulse_output;
00097 
00098   // The control register right-shifted 4 bits; used for waveform table lookup.
00099   reg8 waveform;
00100 
00101   // The remaining control register bits.
00102   reg8 test;
00103   reg8 ring_mod;
00104   reg8 sync;
00105   // The gate bit is handled by the EnvelopeGenerator.
00106 
00107   // DAC input.
00108   reg12 waveform_output;
00109   // Fading time for floating DAC input (waveform 0).
00110   cycle_count floating_output_ttl;
00111 
00112   chip_model sid_model;
00113 
00114   // Sample data for waveforms, not including noise.
00115   unsigned short* wave;
00116   static unsigned short model_wave[2][8][1 << 12];
00117   // DAC lookup tables.
00118   static unsigned short model_dac[2][1 << 12];
00119 
00120 friend class Voice;
00121 friend class SID;
00122 };
00123 
00124 
00125 // ----------------------------------------------------------------------------
00126 // Inline functions.
00127 // The following functions are defined inline because they are called every
00128 // time a sample is calculated.
00129 // ----------------------------------------------------------------------------
00130 
00131 #if RESID_INLINING || defined(RESID_WAVE_CC)
00132 
00133 // ----------------------------------------------------------------------------
00134 // SID clocking - 1 cycle.
00135 // ----------------------------------------------------------------------------
00136 RESID_INLINE
00137 void WaveformGenerator::clock()
00138 {
00139   if (unlikely(test)) {
00140     // Count down time to fully reset shift register.
00141     if (unlikely(shift_register_reset) && unlikely(!--shift_register_reset)) {
00142       reset_shift_register();
00143     }
00144 
00145     // The test bit sets pulse high.
00146     pulse_output = 0xfff;
00147   }
00148   else {
00149     // Calculate new accumulator value;
00150     reg24 accumulator_next = (accumulator + freq) & 0xffffff;
00151     reg24 accumulator_bits_set = ~accumulator & accumulator_next;
00152     accumulator = accumulator_next;
00153 
00154     // Check whether the MSB is set high. This is used for synchronization.
00155     msb_rising = (accumulator_bits_set & 0x800000) ? true : false;
00156 
00157     // Shift noise register once for each time accumulator bit 19 is set high.
00158     // The shift is delayed 2 cycles.
00159     if (unlikely(accumulator_bits_set & 0x080000)) {
00160       // Pipeline: Detect rising bit, shift phase 1, shift phase 2.
00161       shift_pipeline = 2;
00162     }
00163     else if (unlikely(shift_pipeline) && !--shift_pipeline) {
00164       clock_shift_register();
00165     }
00166   }
00167 }
00168 
00169 // ----------------------------------------------------------------------------
00170 // SID clocking - delta_t cycles.
00171 // ----------------------------------------------------------------------------
00172 RESID_INLINE
00173 void WaveformGenerator::clock(cycle_count delta_t)
00174 {
00175   if (unlikely(test)) {
00176     // Count down time to fully reset shift register.
00177     if (shift_register_reset) {
00178       shift_register_reset -= delta_t;
00179       if (unlikely(shift_register_reset <= 0)) {
00180         reset_shift_register();
00181       }
00182     }
00183 
00184     // The test bit sets pulse high.
00185     pulse_output = 0xfff;
00186   }
00187   else {
00188     // Calculate new accumulator value;
00189     reg24 delta_accumulator = delta_t*freq;
00190     reg24 accumulator_next = (accumulator + delta_accumulator) & 0xffffff;
00191     reg24 accumulator_bits_set = ~accumulator & accumulator_next;
00192     accumulator = accumulator_next;
00193 
00194     // Check whether the MSB is set high. This is used for synchronization.
00195     msb_rising = (accumulator_bits_set & 0x800000) ? true : false;
00196 
00197     // NB! Any pipelined shift register clocking from single cycle clocking
00198     // will be lost. It is not worth the trouble to flush the pipeline here.
00199 
00200     // Shift noise register once for each time accumulator bit 19 is set high.
00201     // Bit 19 is set high each time 2^20 (0x100000) is added to the accumulator.
00202     reg24 shift_period = 0x100000;
00203 
00204     while (delta_accumulator) {
00205       if (likely(delta_accumulator < shift_period)) {
00206         shift_period = delta_accumulator;
00207         // Determine whether bit 19 is set on the last period.
00208         // NB! Requires two's complement integer.
00209         if (likely(shift_period <= 0x080000)) {
00210           // Check for flip from 0 to 1.
00211           if (((accumulator - shift_period) & 0x080000) || !(accumulator & 0x080000))
00212             {
00213               break;
00214             }
00215         }
00216         else {
00217           // Check for flip from 0 (to 1 or via 1 to 0) or from 1 via 0 to 1.
00218           if (((accumulator - shift_period) & 0x080000) && !(accumulator & 0x080000))
00219             {
00220               break;
00221             }
00222         }
00223       }
00224 
00225       // Shift the noise/random register.
00226       // NB! The two-cycle pipeline delay is only modeled for 1 cycle clocking.
00227       clock_shift_register();
00228 
00229       delta_accumulator -= shift_period;
00230     }
00231 
00232     // Calculate pulse high/low.
00233     // NB! The one-cycle pipeline delay is only modeled for 1 cycle clocking.
00234     pulse_output = (accumulator >> 12) >= pw ? 0xfff : 0x000;
00235   }
00236 }
00237 
00238 
00239 // ----------------------------------------------------------------------------
00240 // Synchronize oscillators.
00241 // This must be done after all the oscillators have been clock()'ed since the
00242 // oscillators operate in parallel.
00243 // Note that the oscillators must be clocked exactly on the cycle when the
00244 // MSB is set high for hard sync to operate correctly. See SID::clock().
00245 // ----------------------------------------------------------------------------
00246 RESID_INLINE
00247 void WaveformGenerator::synchronize()
00248 {
00249   // A special case occurs when a sync source is synced itself on the same
00250   // cycle as when its MSB is set high. In this case the destination will
00251   // not be synced. This has been verified by sampling OSC3.
00252   if (unlikely(msb_rising) && sync_dest->sync && !(sync && sync_source->msb_rising)) {
00253     sync_dest->accumulator = 0;
00254   }
00255 }
00256 
00257 
00258 // ----------------------------------------------------------------------------
00259 // Waveform output.
00260 // The output from SID 8580 is delayed one cycle compared to SID 6581;
00261 // this is only modeled for single cycle clocking (see sid.cc).
00262 // ----------------------------------------------------------------------------
00263 
00264 // No waveform:
00265 // When no waveform is selected, the DAC input is floating.
00266 //
00267 
00268 // Triangle:
00269 // The upper 12 bits of the accumulator are used.
00270 // The MSB is used to create the falling edge of the triangle by inverting
00271 // the lower 11 bits. The MSB is thrown away and the lower 11 bits are
00272 // left-shifted (half the resolution, full amplitude).
00273 // Ring modulation substitutes the MSB with MSB EOR sync_source MSB.
00274 //
00275 
00276 // Sawtooth:
00277 // The output is identical to the upper 12 bits of the accumulator.
00278 //
00279 
00280 // Pulse:
00281 // The upper 12 bits of the accumulator are used.
00282 // These bits are compared to the pulse width register by a 12 bit digital
00283 // comparator; output is either all one or all zero bits.
00284 // The pulse setting is delayed one cycle after the compare; this is only
00285 // modeled for single cycle clocking.
00286 //
00287 // The test bit, when set to one, holds the pulse waveform output at 0xfff
00288 // regardless of the pulse width setting.
00289 //
00290 
00291 // Noise:
00292 // The noise output is taken from intermediate bits of a 23-bit shift register
00293 // which is clocked by bit 19 of the accumulator.
00294 // The shift is delayed 2 cycles after bit 19 is set high; this is only
00295 // modeled for single cycle clocking.
00296 //
00297 // Operation: Calculate EOR result, shift register, set bit 0 = result.
00298 //
00299 //                reset    -------------------------------------------
00300 //                  |     |                                           |
00301 //           test--OR-->EOR<--                                        |
00302 //                  |         |                                       |
00303 //                  2 2 2 1 1 1 1 1 1 1 1 1 1                         |
00304 // Register bits:   2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 <---
00305 //                      |   |       |     |   |       |     |   |
00306 // Waveform bits:       1   1       9     8   7       6     5   4
00307 //                      1   0
00308 //
00309 // The low 4 waveform bits are zero (grounded).
00310 //
00311 
00312 RESID_INLINE void WaveformGenerator::clock_shift_register()
00313 {
00314   // bit0 = (bit22 | test) ^ bit17
00315   reg24 bit0 = ((shift_register >> 22) ^ (shift_register >> 17)) & 0x1;
00316   shift_register = ((shift_register << 1) | bit0) & 0x7fffff;
00317 
00318   // New noise waveform output.
00319   set_noise_output();
00320 }
00321 
00322 RESID_INLINE void WaveformGenerator::write_shift_register()
00323 {
00324   // Write changes to the shift register output caused by combined waveforms
00325   // back into the shift register.
00326   // A bit once set to zero cannot be changed, hence the and'ing.
00327   // FIXME: Write test program to check the effect of 1 bits and whether
00328   // neighboring bits are affected.
00329 
00330   shift_register &=
00331     ~((1<<20)|(1<<18)|(1<<14)|(1<<11)|(1<<9)|(1<<5)|(1<<2)|(1<<0)) |
00332     ((waveform_output & 0x800) << 9) |  // Bit 11 -> bit 20
00333     ((waveform_output & 0x400) << 8) |  // Bit 10 -> bit 18
00334     ((waveform_output & 0x200) << 5) |  // Bit  9 -> bit 14
00335     ((waveform_output & 0x100) << 3) |  // Bit  8 -> bit 11
00336     ((waveform_output & 0x080) << 2) |  // Bit  7 -> bit  9
00337     ((waveform_output & 0x040) >> 1) |  // Bit  6 -> bit  5
00338     ((waveform_output & 0x020) >> 3) |  // Bit  5 -> bit  2
00339     ((waveform_output & 0x010) >> 4);   // Bit  4 -> bit  0
00340 
00341   noise_output &= waveform_output;
00342   no_noise_or_noise_output = no_noise | noise_output;
00343 }
00344 
00345 RESID_INLINE void WaveformGenerator::reset_shift_register()
00346 {
00347   shift_register = 0x7fffff;
00348   shift_register_reset = 0;
00349 
00350   // New noise waveform output.
00351   set_noise_output();
00352 }
00353 
00354 RESID_INLINE void WaveformGenerator::set_noise_output()
00355 {
00356   noise_output =
00357     ((shift_register & 0x100000) >> 9) |
00358     ((shift_register & 0x040000) >> 8) |
00359     ((shift_register & 0x004000) >> 5) |
00360     ((shift_register & 0x000800) >> 3) |
00361     ((shift_register & 0x000200) >> 2) |
00362     ((shift_register & 0x000020) << 1) |
00363     ((shift_register & 0x000004) << 3) |
00364     ((shift_register & 0x000001) << 4);
00365 
00366   no_noise_or_noise_output = no_noise | noise_output;
00367 }
00368 
00369 // Combined waveforms:
00370 // By combining waveforms, the bits of each waveform are effectively short
00371 // circuited. A zero bit in one waveform will result in a zero output bit
00372 // (thus the infamous claim that the waveforms are AND'ed).
00373 // However, a zero bit in one waveform may also affect the neighboring bits
00374 // in the output.
00375 //
00376 // Example:
00377 // 
00378 //             1 1
00379 // Bit #       1 0 9 8 7 6 5 4 3 2 1 0
00380 //             -----------------------
00381 // Sawtooth    0 0 0 1 1 1 1 1 1 0 0 0
00382 //
00383 // Triangle    0 0 1 1 1 1 1 1 0 0 0 0
00384 //
00385 // AND         0 0 0 1 1 1 1 1 0 0 0 0
00386 //
00387 // Output      0 0 0 0 1 1 1 0 0 0 0 0
00388 //
00389 //
00390 // Re-vectorized die photographs reveal the mechanism behind this behavior.
00391 // Each waveform selector bit acts as a switch, which directly connects
00392 // internal outputs into the waveform DAC inputs as follows:
00393 //
00394 // * Noise outputs the shift register bits to DAC inputs as described above.
00395 //   Each output is also used as input to the next bit when the shift register
00396 //   is shifted.
00397 // * Pulse connects a single line to all DAC inputs. The line is connected to
00398 //   either 5V (pulse on) or 0V (pulse off) at bit 11, and ends at bit 0.
00399 // * Triangle connects the upper 11 bits of the (MSB EOR'ed) accumulator to the
00400 //   DAC inputs, so that DAC bit 0 = 0, DAC bit n = accumulator bit n - 1.
00401 // * Sawtooth connects the upper 12 bits of the accumulator to the DAC inputs,
00402 //   so that DAC bit n = accumulator bit n. Sawtooth blocks out the MSB from
00403 //   the EOR used to generate the triangle waveform.
00404 //
00405 // We can thus draw the following conclusions:
00406 //
00407 // * The shift register may be written to by combined waveforms.
00408 // * The pulse waveform interconnects all bits in combined waveforms via the
00409 //   pulse line.
00410 // * The combination of triangle and sawtooth interconnects neighboring bits
00411 //   of the sawtooth waveform.
00412 //
00413 // This behavior would be quite difficult to model exactly, since the short
00414 // circuits are not binary, but are subject to analog effects. Tests show that
00415 // minor (1 bit) differences can actually occur in the output from otherwise
00416 // identical samples from OSC3 when waveforms are combined. To further
00417 // complicate the situation the output changes slightly with time (more
00418 // neighboring bits are successively set) when the 12-bit waveform
00419 // registers are kept unchanged.
00420 //
00421 // The output is instead approximated by using the upper bits of the
00422 // accumulator as an index to look up the combined output in a table
00423 // containing actual combined waveform samples from OSC3.
00424 // These samples are 8 bit, so 4 bits of waveform resolution is lost.
00425 // All OSC3 samples are taken with FREQ=0x1000, adding a 1 to the upper 12
00426 // bits of the accumulator each cycle for a sample period of 4096 cycles.
00427 //
00428 // Sawtooth+Triangle:
00429 // The accumulator is used to look up an OSC3 sample.
00430 // 
00431 // Pulse+Triangle:
00432 // The accumulator is used to look up an OSC3 sample. When ring modulation is
00433 // selected, the accumulator MSB is substituted with MSB EOR sync_source MSB.
00434 // 
00435 // Pulse+Sawtooth:
00436 // The accumulator is used to look up an OSC3 sample.
00437 // The sample is output if the pulse output is on.
00438 //
00439 // Pulse+Sawtooth+Triangle:
00440 // The accumulator is used to look up an OSC3 sample.
00441 // The sample is output if the pulse output is on.
00442 // 
00443 // Combined waveforms including noise:
00444 // All waveform combinations including noise output zero after a few cycles,
00445 // since the waveform bits are and'ed into the shift register via the shift
00446 // register outputs.
00447 
00448 RESID_INLINE
00449 void WaveformGenerator::set_waveform_output()
00450 {
00451   // Set output value.
00452   if (likely(waveform)) {
00453     // The bit masks no_pulse and no_noise are used to achieve branch-free
00454     // calculation of the output value.
00455     int ix = (accumulator ^ (sync_source->accumulator & ring_msb_mask)) >> 12;
00456     waveform_output =
00457       wave[ix] & (no_pulse | pulse_output) & no_noise_or_noise_output;
00458     if (unlikely(waveform > 0x8)) {
00459       // Combined waveforms write to the shift register.
00460       write_shift_register();
00461     }
00462   }
00463   else {
00464     // Age floating DAC input.
00465     if (likely(floating_output_ttl) && unlikely(!--floating_output_ttl)) {
00466       waveform_output = 0;
00467     }
00468   }
00469 
00470   // The pulse level is defined as (accumulator >> 12) >= pw ? 0xfff : 0x000.
00471   // The expression -((accumulator >> 12) >= pw) & 0xfff yields the same
00472   // results without any branching (and thus without any pipeline stalls).
00473   // NB! This expression relies on that the result of a boolean expression
00474   // is either 0 or 1, and furthermore requires two's complement integer.
00475   // A few more cycles may be saved by storing the pulse width left shifted
00476   // 12 bits, and dropping the and with 0xfff (this is valid since pulse is
00477   // used as a bit mask on 12 bit values), yielding the expression
00478   // -(accumulator >= pw24). However this only results in negligible savings.
00479 
00480   // The result of the pulse width compare is delayed one cycle.
00481   // Push next pulse level into pulse level pipeline.
00482   pulse_output = -((accumulator >> 12) >= pw) & 0xfff;
00483 }
00484 
00485 RESID_INLINE
00486 void WaveformGenerator::set_waveform_output(cycle_count delta_t)
00487 {
00488   // Set output value.
00489   if (likely(waveform)) {
00490     // The bit masks no_pulse and no_noise are used to achieve branch-free
00491     // calculation of the output value.
00492     int ix = (accumulator ^ (sync_source->accumulator & ring_msb_mask)) >> 12;
00493     waveform_output =
00494       wave[ix] & (no_pulse | pulse_output) & no_noise_or_noise_output;
00495     if (unlikely(waveform > 0x8)) {
00496       // Combined waveforms write to the shift register.
00497       // NB! Since cycles are skipped in delta_t clocking, writes will be
00498       // missed. Single cycle clocking must be used for 100% correct operation.
00499       write_shift_register();
00500     }
00501   }
00502   else {
00503     if (likely(floating_output_ttl)) {
00504       // Age floating D/A output.
00505       floating_output_ttl -= delta_t;
00506       if (unlikely(floating_output_ttl <= 0)) {
00507         floating_output_ttl = 0;
00508         waveform_output = 0;
00509       }
00510     }
00511   }
00512 }
00513 
00514 
00515 // ----------------------------------------------------------------------------
00516 // Waveform output (12 bits).
00517 // ----------------------------------------------------------------------------
00518 
00519 // The digital waveform output is converted to an analog signal by a 12-bit
00520 // DAC. Re-vectorized die photographs reveal that the DAC is an R-2R ladder
00521 // built up as follows:
00522 // 
00523 //        12V     11  10   9   8   7   6   5   4   3   2   1   0    GND
00524 // Strange  |      |   |   |   |   |   |   |   |   |   |   |   |     |  Missing
00525 // part    2R     2R  2R  2R  2R  2R  2R  2R  2R  2R  2R  2R  2R    2R  term.
00526 // (bias)   |      |   |   |   |   |   |   |   |   |   |   |   |     |
00527 //          --R-   --R---R---R---R---R---R---R---R---R---R---R--   ---
00528 //                 |          _____
00529 //               __|__     __|__   |
00530 //               -----     =====   |
00531 //               |   |     |   |   |
00532 //        12V ---     -----     ------- GND
00533 //                      |
00534 //                     wout
00535 //
00536 // Bit on:  5V
00537 // Bit off: 0V (GND)
00538 //
00539 // As is the case with all MOS 6581 DACs, the termination to (virtual) ground
00540 // at bit 0 is missing. The MOS 8580 has correct termination, and has also
00541 // done away with the bias part on the left hand side of the figure above.
00542 //
00543 
00544 RESID_INLINE
00545 short WaveformGenerator::output()
00546 {
00547   // DAC imperfections are emulated by using waveform_output as an index
00548   // into a DAC lookup table. readOSC() uses waveform_output directly.
00549   return model_dac[sid_model][waveform_output];
00550 }
00551 
00552 #endif // RESID_INLINING || defined(RESID_WAVE_CC)
00553 
00554 } // namespace reSID
00555 
00556 #endif // not RESID_WAVE_H