rp2040js 1.3.4 → 1.4.0

package/dist/cjs/index.d.ts

@@ -5,7 +5,7 @@ export { I2CMode, I2CSpeed, RPI2C } from './peripherals/i2c.js';
 export { BasePeripheral, type Peripheral } from './peripherals/peripheral.js';
 export { RPPIO, StateMachine } from './peripherals/pio.js';
 export { RPUSBController } from './peripherals/usb.js';
-export { RP2040 } from './rp2040.js';
+export { RP2040, type ClockListener } from './rp2040.js';
 export { Simulator } from './simulator.js';
 export { USBCDC } from './usb/cdc.js';
 export { DataDirection, DescriptorType, SetupRecipient, SetupRequest, SetupType, type ISetupPacketParams, } from './usb/interfaces.js';

package/dist/cjs/peripherals/clocks.d.ts

@@ -22,6 +22,17 @@ export declare class RPClocks extends BasePeripheral implements Peripheral {
     rtcCtrl: number;
     rtcDiv: number;
     constructor(rp2040: RP2040, name: string);
+    /** clk_ref frequency, in Hz. GPIN0/GPIN1 are not modelled and yield 0. */
+    get refFreq(): number;
+    /** clk_sys frequency, in Hz. GPIN0/GPIN1 are not modelled and yield 0. */
+    get sysFreq(): number;
+    /**
+     * clk_peri frequency, in Hz. Feeds the UART and SPI baud rate generators. Returns 0 while
+     * the clock generator is stopped, and for the GPIN0/GPIN1 sources we do not model.
+     */
+    get periFreq(): number;
+    private get refSourceFreq();
+    private get sysSourceFreq();
     readUint32(offset: number): number;
     writeUint32(offset: number, value: number): void;
 }

package/dist/cjs/peripherals/clocks.js

@@ -34,6 +34,44 @@ const CLK_RTC_DIV = 0x70;
 const CLK_RTC_SELECTED = 0x74;
 const CLK_SYS_RESUS_CTRL = 0x78;
 const CLK_SYS_RESUS_STATUS = 0x7c;
+// CLK_REF_CTRL
+const CLK_REF_CTRL_SRC_MASK = 0x3;
+const CLK_REF_CTRL_SRC_ROSC = 0x0;
+const CLK_REF_CTRL_SRC_AUX = 0x1;
+const CLK_REF_CTRL_SRC_XOSC = 0x2;
+const CLK_REF_CTRL_AUXSRC_SHIFT = 5;
+const CLK_REF_CTRL_AUXSRC_MASK = 0x3;
+const CLK_REF_CTRL_AUXSRC_PLL_USB = 0x0;
+// CLK_REF_DIV has no fractional part, only INT (bits 9:8)
+const CLK_REF_DIV_INT_BITS = 0x300;
+// CLK_SYS_CTRL
+const CLK_SYS_CTRL_SRC_MASK = 0x1;
+const CLK_SYS_CTRL_SRC_REF = 0x0;
+const CLK_SYS_CTRL_AUXSRC_SHIFT = 5;
+const CLK_SYS_CTRL_AUXSRC_MASK = 0x7;
+const CLK_SYS_CTRL_AUXSRC_PLL_SYS = 0x0;
+const CLK_SYS_CTRL_AUXSRC_PLL_USB = 0x1;
+const CLK_SYS_CTRL_AUXSRC_ROSC = 0x2;
+const CLK_SYS_CTRL_AUXSRC_XOSC = 0x3;
+// CLK_PERI_CTRL. clk_peri has no SRC mux and no divider: it is driven straight from AUXSRC,
+// which uses its own encoding (not the CLK_SYS one).
+const CLK_PERI_CTRL_ENABLE = 1 << 11;
+const CLK_PERI_CTRL_KILL = 1 << 10;
+const CLK_PERI_CTRL_AUXSRC_SHIFT = 5;
+const CLK_PERI_CTRL_AUXSRC_MASK = 0x7;
+const CLK_PERI_CTRL_AUXSRC_CLK_SYS = 0x0;
+const CLK_PERI_CTRL_AUXSRC_PLL_SYS = 0x1;
+const CLK_PERI_CTRL_AUXSRC_PLL_USB = 0x2;
+const CLK_PERI_CTRL_AUXSRC_ROSC = 0x3;
+const CLK_PERI_CTRL_AUXSRC_XOSC = 0x4;
+// CLK_x_DIV: 24.8 fixed point (INT bits 31:8, FRAC bits 7:0)
+const CLK_DIV_INT_SHIFT = 8;
+const CLK_DIV_FRAC_MASK = 0xff;
+/** Decodes a CLK_x_DIV register value. INT = 0 means divide by 2^16. */
+function clockDivisor(div) {
+    const int = div >>> CLK_DIV_INT_SHIFT;
+    return int ? int + (div & CLK_DIV_FRAC_MASK) / 256 : 0x10000;
+}
 class RPClocks extends peripheral_js_1.BasePeripheral {
     constructor(rp2040, name) {
         super(rp2040, name);
@@ -58,6 +96,71 @@ class RPClocks extends peripheral_js_1.BasePeripheral {
         this.rtcCtrl = 0;
         this.rtcDiv = 0x100;
     }
+    /** clk_ref frequency, in Hz. GPIN0/GPIN1 are not modelled and yield 0. */
+    get refFreq() {
+        return this.refSourceFreq / clockDivisor(this.refDiv & CLK_REF_DIV_INT_BITS);
+    }
+    /** clk_sys frequency, in Hz. GPIN0/GPIN1 are not modelled and yield 0. */
+    get sysFreq() {
+        return this.sysSourceFreq / clockDivisor(this.sysDiv);
+    }
+    /**
+     * clk_peri frequency, in Hz. Feeds the UART and SPI baud rate generators. Returns 0 while
+     * the clock generator is stopped, and for the GPIN0/GPIN1 sources we do not model.
+     */
+    get periFreq() {
+        const { rp2040 } = this;
+        if (!(this.periCtrl & CLK_PERI_CTRL_ENABLE) || this.periCtrl & CLK_PERI_CTRL_KILL) {
+            return 0;
+        }
+        switch ((this.periCtrl >>> CLK_PERI_CTRL_AUXSRC_SHIFT) & CLK_PERI_CTRL_AUXSRC_MASK) {
+            case CLK_PERI_CTRL_AUXSRC_CLK_SYS:
+                return this.sysFreq;
+            case CLK_PERI_CTRL_AUXSRC_PLL_SYS:
+                return rp2040.pllSys.frequency;
+            case CLK_PERI_CTRL_AUXSRC_PLL_USB:
+                return rp2040.pllUsb.frequency;
+            case CLK_PERI_CTRL_AUXSRC_ROSC:
+                return rp2040.roscFreq;
+            case CLK_PERI_CTRL_AUXSRC_XOSC:
+                return rp2040.xoscFreq;
+            default:
+                return 0;
+        }
+    }
+    get refSourceFreq() {
+        const { rp2040 } = this;
+        switch (this.refCtrl & CLK_REF_CTRL_SRC_MASK) {
+            case CLK_REF_CTRL_SRC_ROSC:
+                return rp2040.roscFreq;
+            case CLK_REF_CTRL_SRC_XOSC:
+                return rp2040.xoscFreq;
+            case CLK_REF_CTRL_SRC_AUX: {
+                const auxsrc = (this.refCtrl >>> CLK_REF_CTRL_AUXSRC_SHIFT) & CLK_REF_CTRL_AUXSRC_MASK;
+                return auxsrc === CLK_REF_CTRL_AUXSRC_PLL_USB ? rp2040.pllUsb.frequency : 0;
+            }
+            default:
+                return 0;
+        }
+    }
+    get sysSourceFreq() {
+        const { rp2040 } = this;
+        if ((this.sysCtrl & CLK_SYS_CTRL_SRC_MASK) === CLK_SYS_CTRL_SRC_REF) {
+            return this.refFreq;
+        }
+        switch ((this.sysCtrl >>> CLK_SYS_CTRL_AUXSRC_SHIFT) & CLK_SYS_CTRL_AUXSRC_MASK) {
+            case CLK_SYS_CTRL_AUXSRC_PLL_SYS:
+                return rp2040.pllSys.frequency;
+            case CLK_SYS_CTRL_AUXSRC_PLL_USB:
+                return rp2040.pllUsb.frequency;
+            case CLK_SYS_CTRL_AUXSRC_ROSC:
+                return rp2040.roscFreq;
+            case CLK_SYS_CTRL_AUXSRC_XOSC:
+                return rp2040.xoscFreq;
+            default:
+                return 0;
+        }
+    }
     readUint32(offset) {
         switch (offset) {
             case CLK_GPOUT0_CTRL:
@@ -155,18 +258,23 @@ class RPClocks extends peripheral_js_1.BasePeripheral {
                 break;
             case CLK_REF_CTRL:
                 this.refCtrl = value;
+                this.rp2040.updateClocks();
                 break;
             case CLK_REF_DIV:
                 this.refDiv = value;
+                this.rp2040.updateClocks();
                 break;
             case CLK_SYS_CTRL:
                 this.sysCtrl = value;
+                this.rp2040.updateClocks();
                 break;
             case CLK_SYS_DIV:
                 this.sysDiv = value;
+                this.rp2040.updateClocks();
                 break;
             case CLK_PERI_CTRL:
                 this.periCtrl = value;
+                this.rp2040.updateClocks();
                 break;
             case CLK_PERI_DIV:
                 this.periDiv = value;

package/dist/cjs/peripherals/pll.d.ts

@@ -0,0 +1,25 @@
+import { BasePeripheral, Peripheral } from './peripheral.js';
+/**
+ * RP2040 PLL peripheral.
+ *
+ * Always reports locked (we have no startup delay to model), and computes its output
+ * frequency from the divider registers:
+ *
+ *   f_out = (f_ref / REFDIV * FBDIV) / (POSTDIV1 * POSTDIV2)
+ *
+ * The frequency is what makes `RP2040.clkSys` follow `set_sys_clock_khz()` and friends.
+ */
+export declare class RPPLL extends BasePeripheral implements Peripheral {
+    private cs;
+    private pwr;
+    private fbdivInt;
+    private prim;
+    get refdiv(): number;
+    get fbdiv(): number;
+    get postdiv1(): number;
+    get postdiv2(): number;
+    /** PLL output frequency, in Hz, derived from the current register values. */
+    get frequency(): number;
+    readUint32(offset: number): number;
+    writeUint32(offset: number, value: number): void;
+}

package/dist/cjs/peripherals/pll.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RPPLL = void 0;
+const peripheral_js_1 = require("./peripheral.js");
+// PLL register offsets
+const PLL_CS = 0x00; // Control and Status
+const PLL_PWR = 0x04; // Power control
+const PLL_FBDIV_INT = 0x08; // Feedback divisor
+const PLL_PRIM = 0x0c; // Primary post dividers
+// PLL_CS bits
+const PLL_CS_LOCK = 1 << 31;
+const PLL_CS_BYPASS = 1 << 8;
+const PLL_CS_REFDIV_MASK = 0x3f;
+// PLL_FBDIV_INT bits
+const PLL_FBDIV_INT_MASK = 0xfff;
+// PLL_PRIM bits
+const PLL_PRIM_POSTDIV1_SHIFT = 16;
+const PLL_PRIM_POSTDIV2_SHIFT = 12;
+const PLL_PRIM_POSTDIV_MASK = 0x7;
+/**
+ * RP2040 PLL peripheral.
+ *
+ * Always reports locked (we have no startup delay to model), and computes its output
+ * frequency from the divider registers:
+ *
+ *   f_out = (f_ref / REFDIV * FBDIV) / (POSTDIV1 * POSTDIV2)
+ *
+ * The frequency is what makes `RP2040.clkSys` follow `set_sys_clock_khz()` and friends.
+ */
+class RPPLL extends peripheral_js_1.BasePeripheral {
+    constructor() {
+        super(...arguments);
+        this.cs = 0x1; // REFDIV = 1
+        this.pwr = 0x2d; // VCO and post dividers powered down
+        this.fbdivInt = 0;
+        this.prim = 0x77000; // POSTDIV1 = 7, POSTDIV2 = 7
+    }
+    get refdiv() {
+        return this.cs & PLL_CS_REFDIV_MASK;
+    }
+    get fbdiv() {
+        return this.fbdivInt & PLL_FBDIV_INT_MASK;
+    }
+    get postdiv1() {
+        return (this.prim >>> PLL_PRIM_POSTDIV1_SHIFT) & PLL_PRIM_POSTDIV_MASK;
+    }
+    get postdiv2() {
+        return (this.prim >>> PLL_PRIM_POSTDIV2_SHIFT) & PLL_PRIM_POSTDIV_MASK;
+    }
+    /** PLL output frequency, in Hz, derived from the current register values. */
+    get frequency() {
+        const refFreq = this.rp2040.xoscFreq / (this.refdiv || 1);
+        if (this.cs & PLL_CS_BYPASS) {
+            return refFreq;
+        }
+        const postdiv = (this.postdiv1 || 1) * (this.postdiv2 || 1);
+        return (refFreq * this.fbdiv) / postdiv;
+    }
+    readUint32(offset) {
+        switch (offset) {
+            case PLL_CS:
+                return this.cs | PLL_CS_LOCK;
+            case PLL_PWR:
+                return this.pwr;
+            case PLL_FBDIV_INT:
+                return this.fbdivInt;
+            case PLL_PRIM:
+                return this.prim;
+            default:
+                return super.readUint32(offset);
+        }
+    }
+    writeUint32(offset, value) {
+        switch (offset) {
+            case PLL_CS:
+                this.cs = value;
+                break;
+            case PLL_PWR:
+                this.pwr = value;
+                break;
+            case PLL_FBDIV_INT:
+                this.fbdivInt = value;
+                break;
+            case PLL_PRIM:
+                this.prim = value;
+                break;
+            default:
+                super.writeUint32(offset, value);
+                return;
+        }
+        this.rp2040.updateClocks();
+    }
+}
+exports.RPPLL = RPPLL;

package/dist/cjs/peripherals/uart.d.ts

@@ -28,6 +28,8 @@ export declare class RPUART extends BasePeripheral implements Peripheral {
     get wordLength(): 5 | 6 | 7 | 8 | undefined;
     get baudDivider(): number;
     get baudRate(): number;
+    /** Re-reports the baud rate, unless the firmware has not set the divider yet. */
+    clkPeriChanged(): void;
     get flags(): number;
     checkInterrupts(): void;
     feedByte(value: number): void;

package/dist/cjs/peripherals/uart.js

@@ -80,6 +80,13 @@ class RPUART extends peripheral_js_1.BasePeripheral {
     get baudRate() {
         return Math.round(this.rp2040.clkPeri / (this.baudDivider * 16));
     }
+    /** Re-reports the baud rate, unless the firmware has not set the divider yet. */
+    clkPeriChanged() {
+        var _a;
+        if (this.baudDivider) {
+            (_a = this.onBaudRateChange) === null || _a === void 0 ? void 0 : _a.call(this, this.baudRate);
+        }
+    }
     get flags() {
         return (this.rxFIFO.full ? RXFF : 0) | (this.rxFIFO.empty ? RXFE : 0) | TXFE;
     }

package/dist/cjs/rp2040.d.ts

@@ -2,10 +2,12 @@ import { IClock } from './clock/clock.js';
 import { CortexM0Core } from './cortex-m0-core.js';
 import { GPIOPin } from './gpio-pin.js';
 import { RPADC } from './peripherals/adc.js';
+import { RPClocks } from './peripherals/clocks.js';
 import { RPDMA } from './peripherals/dma.js';
 import { RPI2C } from './peripherals/i2c.js';
 import { Peripheral } from './peripherals/peripheral.js';
 import { RPPIO } from './peripherals/pio.js';
+import { RPPLL } from './peripherals/pll.js';
 import { RPPPB } from './peripherals/ppb.js';
 import { RPPWM } from './peripherals/pwm.js';
 import { RPSPI } from './peripherals/spi.js';
@@ -19,6 +21,11 @@ export declare const RAM_START_ADDRESS = 536870912;
 export declare const APB_START_ADDRESS = 1073741824;
 export declare const DPRAM_START_ADDRESS = 1343225856;
 export declare const SIO_START_ADDRESS = 3489660928;
+/**
+ * Notified after clk_sys changes. Listeners that cache a frequency derived from clk_sys
+ * (PIO clock dividers, for instance) use this to re-derive it.
+ */
+export type ClockListener = (clkSys: number, oldClkSys: number) => void;
 export declare class RP2040 {
     readonly clock: IClock;
     readonly bootrom: Uint32Array<ArrayBuffer>;
@@ -32,6 +39,13 @@ export declare class RP2040 {
     readonly core: CortexM0Core;
     clkSys: number;
     clkPeri: number;
+    /** Crystal oscillator frequency. 12 MHz on the Raspberry Pi Pico and most other boards. */
+    xoscFreq: number;
+    /** Ring oscillator frequency. Varies with voltage/temperature on real silicon. */
+    roscFreq: number;
+    readonly pllSys: RPPLL;
+    readonly pllUsb: RPPLL;
+    readonly clocks: RPClocks;
     readonly ppb: RPPPB;
     readonly sio: RPSIO;
     readonly uart: RPUART[];
@@ -45,6 +59,7 @@ export declare class RP2040 {
     readonly usbCtrl: RPUSBController;
     readonly spi: RPSPI[];
     logger: Logger;
+    private readonly clockListeners;
     readonly peripherals: {
         [index: number]: Peripheral;
     };
@@ -53,6 +68,15 @@ export declare class RP2040 {
     loadBootrom(bootromData: Uint32Array): void;
     reset(): void;
     readUint32(address: number): number;
+    /**
+     * Recomputes `clkSys` and `clkPeri` from the PLL and CLOCKS registers and updates the
+     * peripherals derived from them. Until firmware configures the clock tree, each keeps its default.
+     */
+    updateClocks(): void;
+    private updateClkSys;
+    private updateClkPeri;
+    /** Registers a listener to be notified whenever clk_sys changes. Returns an unsubscribe function. */
+    addClockListener(listener: ClockListener): () => boolean;
     findPeripheral(address: number): Peripheral;
     /** We assume the address is 16-bit aligned */
     readUint16(address: number): number;

package/dist/cjs/rp2040.js

@@ -14,6 +14,7 @@ const io_js_1 = require("./peripherals/io.js");
 const pads_js_1 = require("./peripherals/pads.js");
 const peripheral_js_1 = require("./peripherals/peripheral.js");
 const pio_js_1 = require("./peripherals/pio.js");
+const pll_js_1 = require("./peripherals/pll.js");
 const ppb_js_1 = require("./peripherals/ppb.js");
 const psm_js_1 = require("./peripherals/psm.js");
 const pwm_js_1 = require("./peripherals/pwm.js");
@@ -56,6 +57,13 @@ class RP2040 {
         /* Clocks */
         this.clkSys = 125 * MHz;
         this.clkPeri = 125 * MHz;
+        /** Crystal oscillator frequency. 12 MHz on the Raspberry Pi Pico and most other boards. */
+        this.xoscFreq = 12 * MHz;
+        /** Ring oscillator frequency. Varies with voltage/temperature on real silicon. */
+        this.roscFreq = 6.5 * MHz;
+        this.pllSys = new pll_js_1.RPPLL(this, 'PLL_SYS_BASE');
+        this.pllUsb = new pll_js_1.RPPLL(this, 'PLL_USB_BASE');
+        this.clocks = new clocks_js_1.RPClocks(this, 'CLOCKS_BASE');
         this.ppb = new ppb_js_1.RPPPB(this, 'PPB');
         this.sio = new sio_js_1.RPSIO(this);
         this.uart = [
@@ -128,11 +136,12 @@ class RP2040 {
             }),
         ];
         this.logger = new logging_js_1.ConsoleLogger(logging_js_1.LogLevel.Debug, true);
+        this.clockListeners = new Set();
         this.peripherals = {
             0x18000: new ssi_js_1.RPSSI(this, 'SSI'),
             0x40000: new sysinfo_js_1.RP2040SysInfo(this, 'SYSINFO_BASE'),
             0x40004: new syscfg_js_1.RP2040SysCfg(this, 'SYSCFG'),
-            0x40008: new clocks_js_1.RPClocks(this, 'CLOCKS_BASE'),
+            0x40008: this.clocks,
             0x4000c: new reset_js_1.RPReset(this, 'RESETS_BASE'),
             0x40010: new psm_js_1.RPPSM(this, 'PSM_BASE'),
             0x40014: new io_js_1.RPIO(this, 'IO_BANK0_BASE'),
@@ -140,8 +149,8 @@ class RP2040 {
             0x4001c: new pads_js_1.RPPADS(this, 'PADS_BANK0_BASE', 'bank0'),
             0x40020: new pads_js_1.RPPADS(this, 'PADS_QSPI_BASE', 'qspi'),
             0x40024: new xosc_js_1.RPXOSC(this, 'XOSC_BASE'),
-            0x40028: new peripheral_js_1.UnimplementedPeripheral(this, 'PLL_SYS_BASE'),
-            0x4002c: new peripheral_js_1.UnimplementedPeripheral(this, 'PLL_USB_BASE'),
+            0x40028: this.pllSys,
+            0x4002c: this.pllUsb,
             0x40030: new busctrl_js_1.RPBUSCTRL(this, 'BUSCTRL_BASE'),
             0x40034: this.uart[0],
             0x40038: this.uart[1],
@@ -217,6 +226,46 @@ class RP2040 {
         this.logger.warn(LOG_NAME, `Read from invalid memory address: ${address.toString(16)}`);
         return 0xffffffff;
     }
+    /**
+     * Recomputes `clkSys` and `clkPeri` from the PLL and CLOCKS registers and updates the
+     * peripherals derived from them. Until firmware configures the clock tree, each keeps its default.
+     */
+    updateClocks() {
+        this.updateClkSys();
+        this.updateClkPeri();
+    }
+    updateClkSys() {
+        const clkSys = this.clocks.sysFreq;
+        // 0 means clk_sys is fed from an unmodelled or unconfigured source: keep the last value
+        if (!clkSys || clkSys === this.clkSys) {
+            return;
+        }
+        const oldClkSys = this.clkSys;
+        this.clkSys = clkSys;
+        this.ppb.systickTimer.frequency = clkSys;
+        for (const channel of this.pwm.channels) {
+            channel.timer.frequency = this.pwm.clockFreq;
+        }
+        for (const listener of this.clockListeners) {
+            listener(clkSys, oldClkSys);
+        }
+    }
+    updateClkPeri() {
+        const clkPeri = this.clocks.periFreq;
+        // 0 means the clock generator is stopped, or the source is one we do not model
+        if (!clkPeri || clkPeri === this.clkPeri) {
+            return;
+        }
+        this.clkPeri = clkPeri;
+        for (const uart of this.uart) {
+            uart.clkPeriChanged();
+        }
+    }
+    /** Registers a listener to be notified whenever clk_sys changes. Returns an unsubscribe function. */
+    addClockListener(listener) {
+        this.clockListeners.add(listener);
+        return () => this.clockListeners.delete(listener);
+    }
     findPeripheral(address) {
         return this.peripherals[(address >>> 14) << 2];
     }

package/dist/esm/index.d.ts

@@ -5,7 +5,7 @@ export { I2CMode, I2CSpeed, RPI2C } from './peripherals/i2c.js';
 export { BasePeripheral, type Peripheral } from './peripherals/peripheral.js';
 export { RPPIO, StateMachine } from './peripherals/pio.js';
 export { RPUSBController } from './peripherals/usb.js';
-export { RP2040 } from './rp2040.js';
+export { RP2040, type ClockListener } from './rp2040.js';
 export { Simulator } from './simulator.js';
 export { USBCDC } from './usb/cdc.js';
 export { DataDirection, DescriptorType, SetupRecipient, SetupRequest, SetupType, type ISetupPacketParams, } from './usb/interfaces.js';

package/dist/esm/peripherals/clocks.d.ts

@@ -22,6 +22,17 @@ export declare class RPClocks extends BasePeripheral implements Peripheral {
     rtcCtrl: number;
     rtcDiv: number;
     constructor(rp2040: RP2040, name: string);
+    /** clk_ref frequency, in Hz. GPIN0/GPIN1 are not modelled and yield 0. */
+    get refFreq(): number;
+    /** clk_sys frequency, in Hz. GPIN0/GPIN1 are not modelled and yield 0. */
+    get sysFreq(): number;
+    /**
+     * clk_peri frequency, in Hz. Feeds the UART and SPI baud rate generators. Returns 0 while
+     * the clock generator is stopped, and for the GPIN0/GPIN1 sources we do not model.
+     */
+    get periFreq(): number;
+    private get refSourceFreq();
+    private get sysSourceFreq();
     readUint32(offset: number): number;
     writeUint32(offset: number, value: number): void;
 }

package/dist/esm/peripherals/clocks.js

@@ -31,6 +31,44 @@ const CLK_RTC_DIV = 0x70;
 const CLK_RTC_SELECTED = 0x74;
 const CLK_SYS_RESUS_CTRL = 0x78;
 const CLK_SYS_RESUS_STATUS = 0x7c;
+// CLK_REF_CTRL
+const CLK_REF_CTRL_SRC_MASK = 0x3;
+const CLK_REF_CTRL_SRC_ROSC = 0x0;
+const CLK_REF_CTRL_SRC_AUX = 0x1;
+const CLK_REF_CTRL_SRC_XOSC = 0x2;
+const CLK_REF_CTRL_AUXSRC_SHIFT = 5;
+const CLK_REF_CTRL_AUXSRC_MASK = 0x3;
+const CLK_REF_CTRL_AUXSRC_PLL_USB = 0x0;
+// CLK_REF_DIV has no fractional part, only INT (bits 9:8)
+const CLK_REF_DIV_INT_BITS = 0x300;
+// CLK_SYS_CTRL
+const CLK_SYS_CTRL_SRC_MASK = 0x1;
+const CLK_SYS_CTRL_SRC_REF = 0x0;
+const CLK_SYS_CTRL_AUXSRC_SHIFT = 5;
+const CLK_SYS_CTRL_AUXSRC_MASK = 0x7;
+const CLK_SYS_CTRL_AUXSRC_PLL_SYS = 0x0;
+const CLK_SYS_CTRL_AUXSRC_PLL_USB = 0x1;
+const CLK_SYS_CTRL_AUXSRC_ROSC = 0x2;
+const CLK_SYS_CTRL_AUXSRC_XOSC = 0x3;
+// CLK_PERI_CTRL. clk_peri has no SRC mux and no divider: it is driven straight from AUXSRC,
+// which uses its own encoding (not the CLK_SYS one).
+const CLK_PERI_CTRL_ENABLE = 1 << 11;
+const CLK_PERI_CTRL_KILL = 1 << 10;
+const CLK_PERI_CTRL_AUXSRC_SHIFT = 5;
+const CLK_PERI_CTRL_AUXSRC_MASK = 0x7;
+const CLK_PERI_CTRL_AUXSRC_CLK_SYS = 0x0;
+const CLK_PERI_CTRL_AUXSRC_PLL_SYS = 0x1;
+const CLK_PERI_CTRL_AUXSRC_PLL_USB = 0x2;
+const CLK_PERI_CTRL_AUXSRC_ROSC = 0x3;
+const CLK_PERI_CTRL_AUXSRC_XOSC = 0x4;
+// CLK_x_DIV: 24.8 fixed point (INT bits 31:8, FRAC bits 7:0)
+const CLK_DIV_INT_SHIFT = 8;
+const CLK_DIV_FRAC_MASK = 0xff;
+/** Decodes a CLK_x_DIV register value. INT = 0 means divide by 2^16. */
+function clockDivisor(div) {
+    const int = div >>> CLK_DIV_INT_SHIFT;
+    return int ? int + (div & CLK_DIV_FRAC_MASK) / 256 : 0x10000;
+}
 export class RPClocks extends BasePeripheral {
     constructor(rp2040, name) {
         super(rp2040, name);
@@ -55,6 +93,71 @@ export class RPClocks extends BasePeripheral {
         this.rtcCtrl = 0;
         this.rtcDiv = 0x100;
     }
+    /** clk_ref frequency, in Hz. GPIN0/GPIN1 are not modelled and yield 0. */
+    get refFreq() {
+        return this.refSourceFreq / clockDivisor(this.refDiv & CLK_REF_DIV_INT_BITS);
+    }
+    /** clk_sys frequency, in Hz. GPIN0/GPIN1 are not modelled and yield 0. */
+    get sysFreq() {
+        return this.sysSourceFreq / clockDivisor(this.sysDiv);
+    }
+    /**
+     * clk_peri frequency, in Hz. Feeds the UART and SPI baud rate generators. Returns 0 while
+     * the clock generator is stopped, and for the GPIN0/GPIN1 sources we do not model.
+     */
+    get periFreq() {
+        const { rp2040 } = this;
+        if (!(this.periCtrl & CLK_PERI_CTRL_ENABLE) || this.periCtrl & CLK_PERI_CTRL_KILL) {
+            return 0;
+        }
+        switch ((this.periCtrl >>> CLK_PERI_CTRL_AUXSRC_SHIFT) & CLK_PERI_CTRL_AUXSRC_MASK) {
+            case CLK_PERI_CTRL_AUXSRC_CLK_SYS:
+                return this.sysFreq;
+            case CLK_PERI_CTRL_AUXSRC_PLL_SYS:
+                return rp2040.pllSys.frequency;
+            case CLK_PERI_CTRL_AUXSRC_PLL_USB:
+                return rp2040.pllUsb.frequency;
+            case CLK_PERI_CTRL_AUXSRC_ROSC:
+                return rp2040.roscFreq;
+            case CLK_PERI_CTRL_AUXSRC_XOSC:
+                return rp2040.xoscFreq;
+            default:
+                return 0;
+        }
+    }
+    get refSourceFreq() {
+        const { rp2040 } = this;
+        switch (this.refCtrl & CLK_REF_CTRL_SRC_MASK) {
+            case CLK_REF_CTRL_SRC_ROSC:
+                return rp2040.roscFreq;
+            case CLK_REF_CTRL_SRC_XOSC:
+                return rp2040.xoscFreq;
+            case CLK_REF_CTRL_SRC_AUX: {
+                const auxsrc = (this.refCtrl >>> CLK_REF_CTRL_AUXSRC_SHIFT) & CLK_REF_CTRL_AUXSRC_MASK;
+                return auxsrc === CLK_REF_CTRL_AUXSRC_PLL_USB ? rp2040.pllUsb.frequency : 0;
+            }
+            default:
+                return 0;
+        }
+    }
+    get sysSourceFreq() {
+        const { rp2040 } = this;
+        if ((this.sysCtrl & CLK_SYS_CTRL_SRC_MASK) === CLK_SYS_CTRL_SRC_REF) {
+            return this.refFreq;
+        }
+        switch ((this.sysCtrl >>> CLK_SYS_CTRL_AUXSRC_SHIFT) & CLK_SYS_CTRL_AUXSRC_MASK) {
+            case CLK_SYS_CTRL_AUXSRC_PLL_SYS:
+                return rp2040.pllSys.frequency;
+            case CLK_SYS_CTRL_AUXSRC_PLL_USB:
+                return rp2040.pllUsb.frequency;
+            case CLK_SYS_CTRL_AUXSRC_ROSC:
+                return rp2040.roscFreq;
+            case CLK_SYS_CTRL_AUXSRC_XOSC:
+                return rp2040.xoscFreq;
+            default:
+                return 0;
+        }
+    }
     readUint32(offset) {
         switch (offset) {
             case CLK_GPOUT0_CTRL:
@@ -152,18 +255,23 @@ export class RPClocks extends BasePeripheral {
                 break;
             case CLK_REF_CTRL:
                 this.refCtrl = value;
+                this.rp2040.updateClocks();
                 break;
             case CLK_REF_DIV:
                 this.refDiv = value;
+                this.rp2040.updateClocks();
                 break;
             case CLK_SYS_CTRL:
                 this.sysCtrl = value;
+                this.rp2040.updateClocks();
                 break;
             case CLK_SYS_DIV:
                 this.sysDiv = value;
+                this.rp2040.updateClocks();
                 break;
             case CLK_PERI_CTRL:
                 this.periCtrl = value;
+                this.rp2040.updateClocks();
                 break;
             case CLK_PERI_DIV:
                 this.periDiv = value;

package/dist/esm/peripherals/pll.d.ts

@@ -0,0 +1,25 @@
+import { BasePeripheral, Peripheral } from './peripheral.js';
+/**
+ * RP2040 PLL peripheral.
+ *
+ * Always reports locked (we have no startup delay to model), and computes its output
+ * frequency from the divider registers:
+ *
+ *   f_out = (f_ref / REFDIV * FBDIV) / (POSTDIV1 * POSTDIV2)
+ *
+ * The frequency is what makes `RP2040.clkSys` follow `set_sys_clock_khz()` and friends.
+ */
+export declare class RPPLL extends BasePeripheral implements Peripheral {
+    private cs;
+    private pwr;
+    private fbdivInt;
+    private prim;
+    get refdiv(): number;
+    get fbdiv(): number;
+    get postdiv1(): number;
+    get postdiv2(): number;
+    /** PLL output frequency, in Hz, derived from the current register values. */
+    get frequency(): number;
+    readUint32(offset: number): number;
+    writeUint32(offset: number, value: number): void;
+}

package/dist/esm/peripherals/pll.js

@@ -0,0 +1,90 @@
+import { BasePeripheral } from './peripheral.js';
+// PLL register offsets
+const PLL_CS = 0x00; // Control and Status
+const PLL_PWR = 0x04; // Power control
+const PLL_FBDIV_INT = 0x08; // Feedback divisor
+const PLL_PRIM = 0x0c; // Primary post dividers
+// PLL_CS bits
+const PLL_CS_LOCK = 1 << 31;
+const PLL_CS_BYPASS = 1 << 8;
+const PLL_CS_REFDIV_MASK = 0x3f;
+// PLL_FBDIV_INT bits
+const PLL_FBDIV_INT_MASK = 0xfff;
+// PLL_PRIM bits
+const PLL_PRIM_POSTDIV1_SHIFT = 16;
+const PLL_PRIM_POSTDIV2_SHIFT = 12;
+const PLL_PRIM_POSTDIV_MASK = 0x7;
+/**
+ * RP2040 PLL peripheral.
+ *
+ * Always reports locked (we have no startup delay to model), and computes its output
+ * frequency from the divider registers:
+ *
+ *   f_out = (f_ref / REFDIV * FBDIV) / (POSTDIV1 * POSTDIV2)
+ *
+ * The frequency is what makes `RP2040.clkSys` follow `set_sys_clock_khz()` and friends.
+ */
+export class RPPLL extends BasePeripheral {
+    constructor() {
+        super(...arguments);
+        this.cs = 0x1; // REFDIV = 1
+        this.pwr = 0x2d; // VCO and post dividers powered down
+        this.fbdivInt = 0;
+        this.prim = 0x77000; // POSTDIV1 = 7, POSTDIV2 = 7
+    }
+    get refdiv() {
+        return this.cs & PLL_CS_REFDIV_MASK;
+    }
+    get fbdiv() {
+        return this.fbdivInt & PLL_FBDIV_INT_MASK;
+    }
+    get postdiv1() {
+        return (this.prim >>> PLL_PRIM_POSTDIV1_SHIFT) & PLL_PRIM_POSTDIV_MASK;
+    }
+    get postdiv2() {
+        return (this.prim >>> PLL_PRIM_POSTDIV2_SHIFT) & PLL_PRIM_POSTDIV_MASK;
+    }
+    /** PLL output frequency, in Hz, derived from the current register values. */
+    get frequency() {
+        const refFreq = this.rp2040.xoscFreq / (this.refdiv || 1);
+        if (this.cs & PLL_CS_BYPASS) {
+            return refFreq;
+        }
+        const postdiv = (this.postdiv1 || 1) * (this.postdiv2 || 1);
+        return (refFreq * this.fbdiv) / postdiv;
+    }
+    readUint32(offset) {
+        switch (offset) {
+            case PLL_CS:
+                return this.cs | PLL_CS_LOCK;
+            case PLL_PWR:
+                return this.pwr;
+            case PLL_FBDIV_INT:
+                return this.fbdivInt;
+            case PLL_PRIM:
+                return this.prim;
+            default:
+                return super.readUint32(offset);
+        }
+    }
+    writeUint32(offset, value) {
+        switch (offset) {
+            case PLL_CS:
+                this.cs = value;
+                break;
+            case PLL_PWR:
+                this.pwr = value;
+                break;
+            case PLL_FBDIV_INT:
+                this.fbdivInt = value;
+                break;
+            case PLL_PRIM:
+                this.prim = value;
+                break;
+            default:
+                super.writeUint32(offset, value);
+                return;
+        }
+        this.rp2040.updateClocks();
+    }
+}

package/dist/esm/peripherals/uart.d.ts

@@ -28,6 +28,8 @@ export declare class RPUART extends BasePeripheral implements Peripheral {
     get wordLength(): 5 | 6 | 7 | 8 | undefined;
     get baudDivider(): number;
     get baudRate(): number;
+    /** Re-reports the baud rate, unless the firmware has not set the divider yet. */
+    clkPeriChanged(): void;
     get flags(): number;
     checkInterrupts(): void;
     feedByte(value: number): void;

package/dist/esm/peripherals/uart.js

@@ -77,6 +77,13 @@ export class RPUART extends BasePeripheral {
     get baudRate() {
         return Math.round(this.rp2040.clkPeri / (this.baudDivider * 16));
     }
+    /** Re-reports the baud rate, unless the firmware has not set the divider yet. */
+    clkPeriChanged() {
+        var _a;
+        if (this.baudDivider) {
+            (_a = this.onBaudRateChange) === null || _a === void 0 ? void 0 : _a.call(this, this.baudRate);
+        }
+    }
     get flags() {
         return (this.rxFIFO.full ? RXFF : 0) | (this.rxFIFO.empty ? RXFE : 0) | TXFE;
     }

package/dist/esm/rp2040.d.ts

@@ -2,10 +2,12 @@ import { IClock } from './clock/clock.js';
 import { CortexM0Core } from './cortex-m0-core.js';
 import { GPIOPin } from './gpio-pin.js';
 import { RPADC } from './peripherals/adc.js';
+import { RPClocks } from './peripherals/clocks.js';
 import { RPDMA } from './peripherals/dma.js';
 import { RPI2C } from './peripherals/i2c.js';
 import { Peripheral } from './peripherals/peripheral.js';
 import { RPPIO } from './peripherals/pio.js';
+import { RPPLL } from './peripherals/pll.js';
 import { RPPPB } from './peripherals/ppb.js';
 import { RPPWM } from './peripherals/pwm.js';
 import { RPSPI } from './peripherals/spi.js';
@@ -19,6 +21,11 @@ export declare const RAM_START_ADDRESS = 536870912;
 export declare const APB_START_ADDRESS = 1073741824;
 export declare const DPRAM_START_ADDRESS = 1343225856;
 export declare const SIO_START_ADDRESS = 3489660928;
+/**
+ * Notified after clk_sys changes. Listeners that cache a frequency derived from clk_sys
+ * (PIO clock dividers, for instance) use this to re-derive it.
+ */
+export type ClockListener = (clkSys: number, oldClkSys: number) => void;
 export declare class RP2040 {
     readonly clock: IClock;
     readonly bootrom: Uint32Array<ArrayBuffer>;
@@ -32,6 +39,13 @@ export declare class RP2040 {
     readonly core: CortexM0Core;
     clkSys: number;
     clkPeri: number;
+    /** Crystal oscillator frequency. 12 MHz on the Raspberry Pi Pico and most other boards. */
+    xoscFreq: number;
+    /** Ring oscillator frequency. Varies with voltage/temperature on real silicon. */
+    roscFreq: number;
+    readonly pllSys: RPPLL;
+    readonly pllUsb: RPPLL;
+    readonly clocks: RPClocks;
     readonly ppb: RPPPB;
     readonly sio: RPSIO;
     readonly uart: RPUART[];
@@ -45,6 +59,7 @@ export declare class RP2040 {
     readonly usbCtrl: RPUSBController;
     readonly spi: RPSPI[];
     logger: Logger;
+    private readonly clockListeners;
     readonly peripherals: {
         [index: number]: Peripheral;
     };
@@ -53,6 +68,15 @@ export declare class RP2040 {
     loadBootrom(bootromData: Uint32Array): void;
     reset(): void;
     readUint32(address: number): number;
+    /**
+     * Recomputes `clkSys` and `clkPeri` from the PLL and CLOCKS registers and updates the
+     * peripherals derived from them. Until firmware configures the clock tree, each keeps its default.
+     */
+    updateClocks(): void;
+    private updateClkSys;
+    private updateClkPeri;
+    /** Registers a listener to be notified whenever clk_sys changes. Returns an unsubscribe function. */
+    addClockListener(listener: ClockListener): () => boolean;
     findPeripheral(address: number): Peripheral;
     /** We assume the address is 16-bit aligned */
     readUint16(address: number): number;

package/dist/esm/rp2040.js

@@ -11,6 +11,7 @@ import { RPIO } from './peripherals/io.js';
 import { RPPADS } from './peripherals/pads.js';
 import { UnimplementedPeripheral } from './peripherals/peripheral.js';
 import { RPPIO } from './peripherals/pio.js';
+import { RPPLL } from './peripherals/pll.js';
 import { RPPPB } from './peripherals/ppb.js';
 import { RPPSM } from './peripherals/psm.js';
 import { RPPWM } from './peripherals/pwm.js';
@@ -53,6 +54,13 @@ export class RP2040 {
         /* Clocks */
         this.clkSys = 125 * MHz;
         this.clkPeri = 125 * MHz;
+        /** Crystal oscillator frequency. 12 MHz on the Raspberry Pi Pico and most other boards. */
+        this.xoscFreq = 12 * MHz;
+        /** Ring oscillator frequency. Varies with voltage/temperature on real silicon. */
+        this.roscFreq = 6.5 * MHz;
+        this.pllSys = new RPPLL(this, 'PLL_SYS_BASE');
+        this.pllUsb = new RPPLL(this, 'PLL_USB_BASE');
+        this.clocks = new RPClocks(this, 'CLOCKS_BASE');
         this.ppb = new RPPPB(this, 'PPB');
         this.sio = new RPSIO(this);
         this.uart = [
@@ -125,11 +133,12 @@ export class RP2040 {
             }),
         ];
         this.logger = new ConsoleLogger(LogLevel.Debug, true);
+        this.clockListeners = new Set();
         this.peripherals = {
             0x18000: new RPSSI(this, 'SSI'),
             0x40000: new RP2040SysInfo(this, 'SYSINFO_BASE'),
             0x40004: new RP2040SysCfg(this, 'SYSCFG'),
-            0x40008: new RPClocks(this, 'CLOCKS_BASE'),
+            0x40008: this.clocks,
             0x4000c: new RPReset(this, 'RESETS_BASE'),
             0x40010: new RPPSM(this, 'PSM_BASE'),
             0x40014: new RPIO(this, 'IO_BANK0_BASE'),
@@ -137,8 +146,8 @@ export class RP2040 {
             0x4001c: new RPPADS(this, 'PADS_BANK0_BASE', 'bank0'),
             0x40020: new RPPADS(this, 'PADS_QSPI_BASE', 'qspi'),
             0x40024: new RPXOSC(this, 'XOSC_BASE'),
-            0x40028: new UnimplementedPeripheral(this, 'PLL_SYS_BASE'),
-            0x4002c: new UnimplementedPeripheral(this, 'PLL_USB_BASE'),
+            0x40028: this.pllSys,
+            0x4002c: this.pllUsb,
             0x40030: new RPBUSCTRL(this, 'BUSCTRL_BASE'),
             0x40034: this.uart[0],
             0x40038: this.uart[1],
@@ -214,6 +223,46 @@ export class RP2040 {
         this.logger.warn(LOG_NAME, `Read from invalid memory address: ${address.toString(16)}`);
         return 0xffffffff;
     }
+    /**
+     * Recomputes `clkSys` and `clkPeri` from the PLL and CLOCKS registers and updates the
+     * peripherals derived from them. Until firmware configures the clock tree, each keeps its default.
+     */
+    updateClocks() {
+        this.updateClkSys();
+        this.updateClkPeri();
+    }
+    updateClkSys() {
+        const clkSys = this.clocks.sysFreq;
+        // 0 means clk_sys is fed from an unmodelled or unconfigured source: keep the last value
+        if (!clkSys || clkSys === this.clkSys) {
+            return;
+        }
+        const oldClkSys = this.clkSys;
+        this.clkSys = clkSys;
+        this.ppb.systickTimer.frequency = clkSys;
+        for (const channel of this.pwm.channels) {
+            channel.timer.frequency = this.pwm.clockFreq;
+        }
+        for (const listener of this.clockListeners) {
+            listener(clkSys, oldClkSys);
+        }
+    }
+    updateClkPeri() {
+        const clkPeri = this.clocks.periFreq;
+        // 0 means the clock generator is stopped, or the source is one we do not model
+        if (!clkPeri || clkPeri === this.clkPeri) {
+            return;
+        }
+        this.clkPeri = clkPeri;
+        for (const uart of this.uart) {
+            uart.clkPeriChanged();
+        }
+    }
+    /** Registers a listener to be notified whenever clk_sys changes. Returns an unsubscribe function. */
+    addClockListener(listener) {
+        this.clockListeners.add(listener);
+        return () => this.clockListeners.delete(listener);
+    }
     findPeripheral(address) {
         return this.peripherals[(address >>> 14) << 2];
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rp2040js",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "Raspberry Pi Pico (RP2040) Emulator",
   "repository": {
     "type": "git",