@gba-kit/arm-emulator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Macabeus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @gba-kit/arm-emulator
+
+Pure ARM7TDMI CPU emulator supporting both Thumb (16-bit) and ARM (32-bit) instruction sets.
+
+> Note: It doesn't include any GBA-specific logic. The CPU accepts a `MemoryBus` interface and an optional SWI handler callback, so it can be embedded in any ARM7TDMI-based system.
+
+## Install
+
+```bash
+npm install @gba-kit/arm-emulator
+```
+
+## Usage
+
+### ARM CPU
+
+```typescript
+import { GbaMemory } from '@gba-kit/arm-emulator';
+import { ArmCpu } from '@gba-kit/arm-emulator/arm-cpu';
+
+const memory = new GbaMemory();
+const cpu = new ArmCpu(memory, {
+  swiHandler: (cpu, swiNumber) => {
+    // Platform-specific SWI handling
+  },
+});
+
+cpu.registers[15] = 0x08000000; // set PC
+cpu.step(); // execute one instruction
+```
+
+### Disassembly
+
+```typescript
+import { disassembleArm, disassembleThumb } from '@gba-kit/arm-emulator/disassembler';
+
+const mnemonic = disassembleThumb(0x4770, 0x08000000);
+// "bx lr"
+```
+
+## Exports
+
+### Main entry (`@gba-kit/arm-emulator`)
+
+| Export                            | Type  | Description                     |
+| --------------------------------- | ----- | ------------------------------- |
+| `GbaMemory`                       | class | Memory bus with region dispatch |
+| `PC`, `LR`, `SP`, `SENTINEL_ADDR` | const | Register index constants        |
+
+Types: `CpsrFlags`, `DebugAction`, `DebugHooks`, `ExecutionResult`, `ExternalCall`, `MemoryBus`, `MemoryWrite`, `CpuSnapshot`
+
+### Subpath exports
+
+| Subpath                              | Description                                                          |
+| ------------------------------------ | -------------------------------------------------------------------- |
+| `@gba-kit/arm-emulator/arm-cpu`      | `ArmCpu` class — full ARM7TDMI with mode switching, banked registers |
+| `@gba-kit/arm-emulator/disassembler` | `disassembleArm()`, `disassembleThumb()` functions                   |
+| `@gba-kit/arm-emulator/cpu-snapshot` | `CpuSnapshot` interface for serializable CPU state                   |
+
+## Testing
+
+```bash
+pnpm test
+```

package/dist/arm-cpu.d.ts

@@ -0,0 +1,141 @@
+/**
+ * ARM7TDMI Full CPU Emulator
+ *
+ * Supports both ARM (32-bit) and Thumb (16-bit) instruction sets,
+ * CPU modes with banked registers, and HLE BIOS calls via SWI.
+ *
+ * This class is the full-featured CPU for the GBA emulator.
+ *
+ * References:
+ * - ARM7TDMI TRM (DDI0029G): https://ww1.microchip.com/downloads/en/DeviceDoc/DDI0029G_7TDMI_R3_trm.pdf
+ * - GBATEK: http://problemkaputt.de/gbatek.htm
+ */
+import type { CpuSnapshot } from './cpu-snapshot.js';
+import type { CpsrFlags, DebugHooks, ExecutionResult, MemoryBus } from './types.js';
+/** CPU mode codes (bits 4-0 of CPSR) */
+export declare const MODE_USR = 16;
+export declare const MODE_FIQ = 17;
+export declare const MODE_IRQ = 18;
+export declare const MODE_SVC = 19;
+export declare const MODE_ABT = 23;
+export declare const MODE_UND = 27;
+export declare const MODE_SYS = 31;
+/**
+ * Callback for Software Interrupt (SWI) instructions.
+ * Platform-specific: on GBA, the SWI number selects a BIOS function.
+ * If not provided, SWI instructions are silently ignored.
+ */
+export type SwiHandler = (cpu: ArmCpu, swiNumber: number) => void;
+/**
+ * Full ARM7TDMI CPU supporting ARM and Thumb instruction sets,
+ * with CPU modes and banked registers.
+ */
+export declare class ArmCpu {
+    #private;
+    /** General-purpose registers r0-r15 (current view, mode-dependent) */
+    readonly registers: Uint32Array<ArrayBuffer>;
+    /**
+     * Current Program Status Register (full 32-bit).
+     *
+     * Bit layout:
+     * - 31: N (Negative)
+     * - 30: Z (Zero)
+     * - 29: C (Carry)
+     * - 28: V (Overflow)
+     * - 7: I (IRQ disable)
+     * - 6: F (FIQ disable)
+     * - 5: T (Thumb state: 0=ARM, 1=Thumb)
+     * - 4-0: Mode (0x10=USR, 0x11=FIQ, 0x12=IRQ, 0x13=SVC, 0x17=ABT, 0x1B=UND, 0x1F=SYS)
+     */
+    cpsr: number;
+    /** Memory bus */
+    readonly memory: MemoryBus;
+    constructor(memory: MemoryBus, options?: {
+        hooks?: DebugHooks;
+        swiHandler?: SwiHandler;
+    });
+    /**
+     * Set the banked SP for a given mode without switching modes.
+     * Used to initialize stack pointers (e.g. GBA BIOS sets IRQ/SVC stacks).
+     */
+    setBankedSP(mode: number, value: number): void;
+    /** Get condition flags from CPSR as a CpsrFlags object */
+    get flags(): CpsrFlags;
+    /** Get Negative flag */
+    getN(): boolean;
+    /** Get Zero flag */
+    getZ(): boolean;
+    /** Get Carry flag */
+    getC(): boolean;
+    /** Get Overflow flag */
+    getV(): boolean;
+    /** Get Thumb state bit */
+    getT(): boolean;
+    /** Get current CPU mode */
+    getMode(): number;
+    /** Set Negative flag */
+    setN(val: boolean): void;
+    /** Set Zero flag */
+    setZ(val: boolean): void;
+    /** Set Carry flag */
+    setC(val: boolean): void;
+    /** Set Overflow flag */
+    setV(val: boolean): void;
+    /** Set Thumb state bit */
+    setT(val: boolean): void;
+    /** Set all four condition flags at once from an AluResult */
+    setFlags(n: boolean, z: boolean, c: boolean, v: boolean): void;
+    /** Set NZ flags from a result value, leave C and V unchanged */
+    setNZ(result: number): void;
+    /** Get the SPSR for the current mode. Returns 0 for USR/SYS (no SPSR). */
+    getSPSR(): number;
+    /** Set the SPSR for the current mode. No-op for USR/SYS. */
+    setSPSR(value: number): void;
+    /**
+     * Switch CPU mode. Saves banked registers from the old mode
+     * and restores them for the new mode.
+     */
+    switchMode(newMode: number): void;
+    /** Attach or detach debug hooks */
+    setDebugHooks(hooks: DebugHooks | undefined): void;
+    /** Register a stub for an external function call */
+    registerStub(symbolName: string): number;
+    /** Serialize to a plain snapshot. */
+    serialize(): CpuSnapshot;
+    /** Restore from a snapshot. */
+    deserialize(snap: CpuSnapshot): void;
+    /** Reset CPU state for a new execution */
+    resetState(): void;
+    /** Check if IRQs are disabled (CPSR I bit set) */
+    irqDisabled(): boolean;
+    /**
+     * Enter IRQ exception.
+     *
+     * Standard ARM7TDMI exception entry:
+     * 1. Save CPSR to SPSR_irq
+     * 2. Switch to IRQ mode
+     * 3. Set LR_irq to return address (next instruction + 4)
+     * 4. Set I bit (disable further IRQs)
+     * 5. Clear T bit (enter ARM state)
+     * 6. Set PC to IRQ vector (0x00000018)
+     *
+     * The BIOS stub at 0x18 (installed by Gba.#installBiosStub) handles:
+     * - Saving registers to IRQ stack
+     * - Calling the user's handler from [0x03007FFC]
+     * - Restoring registers and returning from IRQ
+     *
+     * The BIOS stub at 0x80 handles IE/IF acknowledgment and BIOS IF mirror
+     * update before calling the user handler.
+     */
+    enterIrq(): void;
+    /** Enter Undefined Instruction exception */
+    enterUnd(instrAddr: number): void;
+    /**
+     * Execute one instruction (ARM or Thumb based on T bit).
+     * Returns false if halted.
+     */
+    step(): boolean;
+    /** Run until halt or instruction limit */
+    run(maxInstructions: number): ExecutionResult;
+}
+//# sourceMappingURL=arm-cpu.d.ts.map

package/dist/arm-cpu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arm-cpu.d.ts","sourceRoot":"","sources":["../src/arm-cpu.ts"],"names":[],"mappings":"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"}