perf!: centeral timekeeping

This should improve performance, especially when running simulations with
multiple peripherals. For instance, the demo project now runs at ~322%,
up from ~185% in AVR8js 0.13.1.

BREAKING CHANGE: `tick()` methods were removed from individual peripherals.
You now need to call `cpu.tick()` instead.

Author: urish

demo/src/execute.ts

@@ -50,10 +50,6 @@ export class AVRRunner {
     const cyclesToRun = this.cpu.cycles + this.workUnitCycles;
     while (this.cpu.cycles < cyclesToRun) {
       avrInstruction(this.cpu);
-      this.timer0.tick();
-      this.timer1.tick();
-      this.timer2.tick();
-      this.usart.tick();
       this.cpu.tick();
     }
 

src/cpu/cpu.ts

@@ -55,6 +55,13 @@ export interface AVRInterruptConfig {
   constant?: boolean;
 }
 
+export type AVRClockEventCallback = () => void;
+
+interface AVRClockEventEntry {
+  cycles: number;
+  callback: AVRClockEventCallback;
+}
+
 export class CPU implements ICPU {
   readonly data: Uint8Array = new Uint8Array(this.sramBytes + registerSpace);
   readonly data16 = new Uint16Array(this.data.buffer);
@@ -63,6 +70,7 @@ export class CPU implements ICPU {
   readonly readHooks: CPUMemoryReadHooks = [];
   readonly writeHooks: CPUMemoryHooks = [];
   private readonly pendingInterrupts: AVRInterruptConfig[] = [];
+  private readonly clockEvents: AVRClockEventEntry[] = [];
   readonly pc22Bits = this.progBytes.length > 0x20000;
 
   // This lets the Timer Compare output override GPIO pins:
@@ -71,6 +79,7 @@ export class CPU implements ICPU {
   pc: u32 = 0;
   cycles: u32 = 0;
   nextInterrupt: i16 = -1;
+  private nextClockEvent: u32 = 0;
 
   constructor(public progMem: Uint16Array, private sramBytes = 8192) {
     this.reset();
@@ -164,10 +173,44 @@ export class CPU implements ICPU {
     }
   }
 
+  private updateClockEvents() {
+    this.clockEvents.sort((a, b) => a.cycles - b.cycles);
+    this.nextClockEvent = this.clockEvents[0]?.cycles ?? 0;
+  }
+
+  addClockEvent(callback: AVRClockEventCallback, cycles: number) {
+    const entry = { cycles: this.cycles + Math.max(1, cycles), callback };
+    this.clockEvents.push(entry);
+    this.updateClockEvents();
+    return callback;
+  }
+
+  updateClockEvent(callback: AVRClockEventCallback, cycles: number) {
+    const entry = this.clockEvents.find((item) => (item.callback = callback));
+    if (entry) {
+      entry.cycles = this.cycles + Math.max(1, cycles);
+      this.updateClockEvents();
+      return true;
+    }
+    return false;
+  }
+
+  clearClockEvent(callback: AVRClockEventCallback) {
+    const index = this.clockEvents.findIndex((item) => (item.callback = callback));
+    if (index >= 0) {
+      this.clockEvents.splice(index, 1);
+      this.updateClockEvents();
+    }
+  }
+
   tick() {
+    if (this.nextClockEvent && this.nextClockEvent <= this.cycles) {
+      const clockEvent = this.clockEvents.shift();
+      clockEvent?.callback();
+      this.nextClockEvent = this.clockEvents[0]?.cycles ?? 0;
+    }
     if (this.interruptsEnabled && this.nextInterrupt >= 0) {
       const interrupt = this.pendingInterrupts[this.nextInterrupt];
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       avrInterrupt(this, interrupt.address);
       if (!interrupt.constant) {
         this.clearInterrupt(interrupt);

src/peripherals/eeprom.spec.ts

@@ -23,11 +23,10 @@ describe('EEPROM', () => {
   describe('Reading the EEPROM', () => {
     it('should return 0xff when reading from an empty location', () => {
       const cpu = new CPU(new Uint16Array(0x1000));
-      const eeprom = new AVREEPROM(cpu, new EEPROMMemoryBackend(1024));
+      new AVREEPROM(cpu, new EEPROMMemoryBackend(1024));
       cpu.writeData(EEARL, 0);
       cpu.writeData(EEARH, 0);
       cpu.writeData(EECR, EERE);
-      eeprom.tick();
       cpu.tick();
       expect(cpu.cycles).toEqual(4);
       expect(cpu.data[EEDR]).toEqual(0xff);
@@ -36,12 +35,11 @@ describe('EEPROM', () => {
     it('should return the value stored at the given EEPROM address', () => {
       const cpu = new CPU(new Uint16Array(0x1000));
       const eepromBackend = new EEPROMMemoryBackend(1024);
-      const eeprom = new AVREEPROM(cpu, eepromBackend);
+      new AVREEPROM(cpu, eepromBackend);
       eepromBackend.memory[0x250] = 0x42;
       cpu.writeData(EEARL, 0x50);
       cpu.writeData(EEARH, 0x2);
       cpu.writeData(EECR, EERE);
-      eeprom.tick();
       cpu.tick();
       expect(cpu.data[EEDR]).toEqual(0x42);
     });
@@ -51,13 +49,12 @@ describe('EEPROM', () => {
     it('should write a byte to the given EEPROM address', () => {
       const cpu = new CPU(new Uint16Array(0x1000));
       const eepromBackend = new EEPROMMemoryBackend(1024);
-      const eeprom = new AVREEPROM(cpu, eepromBackend);
+      new AVREEPROM(cpu, eepromBackend);
       cpu.writeData(EEDR, 0x55);
       cpu.writeData(EEARL, 15);
       cpu.writeData(EEARH, 0);
       cpu.writeData(EECR, EEMPE);
       cpu.writeData(EECR, EEPE);
-      eeprom.tick();
       cpu.tick();
       expect(cpu.cycles).toEqual(2);
       expect(eepromBackend.memory[15]).toEqual(0x55);
@@ -84,10 +81,10 @@ describe('EEPROM', () => {
 
       const cpu = new CPU(program);
       const eepromBackend = new EEPROMMemoryBackend(1024);
-      const eeprom = new AVREEPROM(cpu, eepromBackend);
+      new AVREEPROM(cpu, eepromBackend);
       eepromBackend.memory[9] = 0x0f; // high four bits are cleared
 
-      const runner = new TestProgramRunner(cpu, eeprom);
+      const runner = new TestProgramRunner(cpu);
       runner.runInstructions(instructionCount);
 
       // EEPROM was 0x0f, and our program wrote 0x55.
@@ -98,22 +95,20 @@ describe('EEPROM', () => {
     it('should clear the EEPE bit and fire an interrupt when write has been completed', () => {
       const cpu = new CPU(new Uint16Array(0x1000));
       const eepromBackend = new EEPROMMemoryBackend(1024);
-      const eeprom = new AVREEPROM(cpu, eepromBackend);
+      new AVREEPROM(cpu, eepromBackend);
       cpu.writeData(EEDR, 0x55);
       cpu.writeData(EEARL, 15);
       cpu.writeData(EEARH, 0);
       cpu.writeData(EECR, EEMPE | EERIE);
       cpu.data[SREG] = 0x80; // SREG: I-------
       cpu.writeData(EECR, EEPE);
       cpu.cycles += 1000;
-      eeprom.tick();
       cpu.tick();
       // At this point, write shouldn't be complete yet
       expect(cpu.data[EECR] & EEPE).toEqual(EEPE);
       expect(cpu.pc).toEqual(0);
       cpu.cycles += 10000000;
       // And now, 10 million cycles later, it should.
-      eeprom.tick();
       cpu.tick();
       expect(eepromBackend.memory[15]).toEqual(0x55);
       expect(cpu.data[EECR] & EEPE).toEqual(0);
@@ -123,16 +118,14 @@ describe('EEPROM', () => {
     it('should skip the write if EEMPE is clear', () => {
       const cpu = new CPU(new Uint16Array(0x1000));
       const eepromBackend = new EEPROMMemoryBackend(1024);
-      const eeprom = new AVREEPROM(cpu, eepromBackend);
+      new AVREEPROM(cpu, eepromBackend);
       cpu.writeData(EEDR, 0x55);
       cpu.writeData(EEARL, 15);
       cpu.writeData(EEARH, 0);
       cpu.writeData(EECR, EEMPE);
       cpu.cycles = 8; // waiting for more than 4 cycles should clear EEMPE
-      eeprom.tick();
       cpu.tick();
       cpu.writeData(EECR, EEPE);
-      eeprom.tick();
       cpu.tick();
       // Ensure that nothing was written, and EEPE bit is clear
       expect(cpu.cycles).toEqual(8);
@@ -143,15 +136,14 @@ describe('EEPROM', () => {
     it('should skip the write if another write is already in progress', () => {
       const cpu = new CPU(new Uint16Array(0x1000));
       const eepromBackend = new EEPROMMemoryBackend(1024);
-      const eeprom = new AVREEPROM(cpu, eepromBackend);
+      new AVREEPROM(cpu, eepromBackend);
 
       // Write 0x55 to address 15
       cpu.writeData(EEDR, 0x55);
       cpu.writeData(EEARL, 15);
       cpu.writeData(EEARH, 0);
       cpu.writeData(EECR, EEMPE);
       cpu.writeData(EECR, EEPE);
-      eeprom.tick();
       cpu.tick();
       expect(cpu.cycles).toEqual(2);
 
@@ -161,7 +153,6 @@ describe('EEPROM', () => {
       cpu.writeData(EEARH, 0);
       cpu.writeData(EECR, EEMPE);
       cpu.writeData(EECR, EEPE);
-      eeprom.tick();
       cpu.tick();
 
       // Ensure that second write didn't happen
@@ -173,21 +164,19 @@ describe('EEPROM', () => {
     it('should write two bytes sucessfully', () => {
       const cpu = new CPU(new Uint16Array(0x1000));
       const eepromBackend = new EEPROMMemoryBackend(1024);
-      const eeprom = new AVREEPROM(cpu, eepromBackend);
+      new AVREEPROM(cpu, eepromBackend);
 
       // Write 0x55 to address 15
       cpu.writeData(EEDR, 0x55);
       cpu.writeData(EEARL, 15);
       cpu.writeData(EEARH, 0);
       cpu.writeData(EECR, EEMPE);
       cpu.writeData(EECR, EEPE);
-      eeprom.tick();
       cpu.tick();
       expect(cpu.cycles).toEqual(2);
 
       // wait long enough time for the first write to finish
       cpu.cycles += 10000000;
-      eeprom.tick();
       cpu.tick();
 
       // Write 0x66 to address 16
@@ -196,7 +185,6 @@ describe('EEPROM', () => {
       cpu.writeData(EEARH, 0);
       cpu.writeData(EECR, EEMPE);
       cpu.writeData(EECR, EEPE);
-      eeprom.tick();
       cpu.tick();
 
       // Ensure both writes took place
@@ -226,10 +214,10 @@ describe('EEPROM', () => {
 
       const cpu = new CPU(program);
       const eepromBackend = new EEPROMMemoryBackend(1024);
-      const eeprom = new AVREEPROM(cpu, eepromBackend);
+      new AVREEPROM(cpu, eepromBackend);
       eepromBackend.memory[9] = 0x22;
 
-      const runner = new TestProgramRunner(cpu, eeprom);
+      const runner = new TestProgramRunner(cpu);
       runner.runInstructions(instructionCount);
 
       expect(eepromBackend.memory[9]).toEqual(0xff);

src/peripherals/eeprom.ts

@@ -95,7 +95,11 @@ export class AVREEPROM {
       }
 
       if (eecr & EEMPE) {
-        this.writeEnabledCycles = this.cpu.cycles + 4;
+        const eempeCycles = 4;
+        this.writeEnabledCycles = this.cpu.cycles + eempeCycles;
+        this.cpu.addClockEvent(() => {
+          this.cpu.data[EECR] &= ~EEMPE;
+        }, eempeCycles);
       }
 
       // Read
@@ -134,6 +138,11 @@ export class AVREEPROM {
         }
 
         this.cpu.data[EECR] |= EEPE;
+
+        this.cpu.addClockEvent(() => {
+          this.cpu.setInterruptFlag(this.EER);
+        }, this.writeCompleteCycles - this.cpu.cycles);
+
         // When EEPE has been set, the CPU is halted for two cycles before the
         // next instruction is executed.
         this.cpu.cycles += 2;
@@ -143,15 +152,4 @@ export class AVREEPROM {
       return false;
     };
   }
-
-  tick() {
-    const { EECR } = this.config;
-
-    if (this.writeEnabledCycles && this.cpu.cycles > this.writeEnabledCycles) {
-      this.cpu.data[EECR] &= ~EEMPE;
-    }
-    if (this.writeCompleteCycles && this.cpu.cycles > this.writeCompleteCycles) {
-      this.cpu.setInterruptFlag(this.EER);
-    }
-  }
 }

src/peripherals/spi.spec.ts

@@ -160,7 +160,7 @@ describe('SPI', () => {
       return 0x5b; // we copy this byte to
     };
 
-    const runner = new TestProgramRunner(cpu, spi);
+    const runner = new TestProgramRunner(cpu);
     runner.runToBreak();
 
     // 16 cycles per clock * 8 bits = 128
@@ -172,11 +172,10 @@ describe('SPI', () => {
 
   it('should set the WCOL bit in SPSR if writing to SPDR while SPI is already transmitting', () => {
     const cpu = new CPU(new Uint16Array(1024));
-    const spi = new AVRSPI(cpu, spiConfig, FREQ_16MHZ);
+    new AVRSPI(cpu, spiConfig, FREQ_16MHZ);
 
     cpu.writeData(SPCR, SPE | MSTR);
     cpu.writeData(SPDR, 0x50);
-    spi.tick();
     cpu.tick();
     expect(cpu.readData(SPSR) & WCOL).toEqual(0);
 
@@ -186,21 +185,19 @@ describe('SPI', () => {
 
   it('should clear the SPIF bit and fire an interrupt when SPI transfer completes', () => {
     const cpu = new CPU(new Uint16Array(1024));
-    const spi = new AVRSPI(cpu, spiConfig, FREQ_16MHZ);
+    new AVRSPI(cpu, spiConfig, FREQ_16MHZ);
 
     cpu.writeData(SPCR, SPE | SPIE | MSTR);
     cpu.writeData(SPDR, 0x50);
     cpu.data[SREG] = 0x80; // SREG: I-------
 
     // At this point, write shouldn't be complete yet
     cpu.cycles += 10;
-    spi.tick();
     cpu.tick();
     expect(cpu.pc).toEqual(0);
 
     // 100 cycles later, it should (8 bits * 8 cycles per bit = 64).
     cpu.cycles += 100;
-    spi.tick();
     cpu.tick();
     expect(cpu.data[SPSR] & SPIF).toEqual(0);
     expect(cpu.pc).toEqual(0x22); // SPI Ready interrupt
@@ -215,12 +212,10 @@ describe('SPI', () => {
     cpu.writeData(SPDR, 0x8f);
 
     cpu.cycles = 10;
-    spi.tick();
     cpu.tick();
     expect(cpu.readData(SPDR)).toEqual(0);
 
     cpu.cycles = 32; // 4 cycles per bit * 8 bits = 32
-    spi.tick();
     cpu.tick();
     expect(cpu.readData(SPDR)).toEqual(0x88);
   });