@specy/risc-v 3.3.1 → 3.4.0

package/dist/index.d.mts

@@ -350,6 +350,20 @@ declare enum RISCVRegisters {
 }
 type RegisterName = keyof typeof RISCVRegisters;
 declare const RISCV_REGISTERS: RegisterName[];
+/**
+ * The floating point registers, in the order `getFloatingPointRegistersValues` returns them, which
+ * is the order the core holds them in: register number 0 to 31, spelled as RARS spells them.
+ */
+declare const RISCV_FLOATING_POINT_REGISTERS: readonly ["ft0", "ft1", "ft2", "ft3", "ft4", "ft5", "ft6", "ft7", "fs0", "fs1", "fa0", "fa1", "fa2", "fa3", "fa4", "fa5", "fa6", "fa7", "fs2", "fs3", "fs4", "fs5", "fs6", "fs7", "fs8", "fs9", "fs10", "fs11", "ft8", "ft9", "ft10", "ft11"];
+type FloatingPointRegisterName = typeof RISCV_FLOATING_POINT_REGISTERS[number];
+/**
+ * The control and status registers the core implements, in the order
+ * `getControlAndStatusRegistersValues` returns them. `fflags` and `frm` are windows onto `fcsr`,
+ * and `cycleh`, `timeh` and `instreth` are the high halves of `cycle`, `time` and `instret`, so
+ * those pairs always agree.
+ */
+declare const RISCV_CSR_REGISTERS: readonly ["ustatus", "fflags", "frm", "fcsr", "uie", "utvec", "uscratch", "uepc", "ucause", "utval", "uip", "cycle", "time", "instret", "cycleh", "timeh", "instreth"];
+type CsrRegisterName = typeof RISCV_CSR_REGISTERS[number];
 type HandlerName = keyof HandlerMap;
 /**
  * A handler may return its result directly, or a promise of it. When a handler returns a promise
@@ -386,10 +400,6 @@ interface JsRiscV {
      * it settles once that handler and the rest of the instruction have finished.
      */
     step(): Promise<StopReason>;
-    /**
-     * Gets the 8 condition flags.
-     */
-    getConditionFlags(): number[];
     /**
      * Sets the size of the undo stack, must be called before assembling the program.
      * @param size
@@ -505,6 +515,47 @@ interface JsRiscV {
      * @returns An array containing the register values in long format. The order of the values is implementation defined.
      */
     getRegistersValuesLong(): string[];
+    /**
+     * Gets every floating point register as a high/low pair of 32 bit halves: element `2 * i` is
+     * the high half of register `i` and `2 * i + 1` its low half, so the array holds 64 numbers.
+     * The registers are in `RISCV_FLOATING_POINT_REGISTERS` order, and both halves matter on both
+     * targets: the file is 64 bit wide even on RV32, where a single is NaN-boxed into it (its high
+     * half is `0xFFFFFFFF`).
+     *
+     * The core hands this over as an `Int32Array` of signed 32 bit halves, so a half with its top
+     * bit set reads back negative: compose each pair with `highLowToBigint`, which takes both
+     * halves unsigned, rather than mapping `>>> 0` over the array (a typed array's `map` truncates
+     * the result back to int32, handing you the negative value again).
+     *
+     * Pairs rather than decimal strings because this is read on every panel refresh, and a 64 bit
+     * conversion per register is the kind of work that costs in the compiled core.
+     */
+    getFloatingPointRegistersValues(): Int32Array;
+    /**
+     * Sets one floating point register, writing it directly: no undo entry is recorded, because
+     * presetting a register from the host is not something the program did. Split the value with
+     * `bigintToHighLow`, and NaN-box a single yourself (`0xFFFFFFFFn << 32n | bits`) if that is
+     * what you mean.
+     * @param index Position in `RISCV_FLOATING_POINT_REGISTERS`. Must be a whole number from 0 to
+     * 31; anything else throws.
+     */
+    setFloatingPointRegisterValue(index: number, high: number, low: number): void;
+    /**
+     * Gets every control and status register as a high/low pair, in the same shape as
+     * `getFloatingPointRegistersValues`: an `Int32Array` of 34 signed halves for the 17 registers
+     * of `RISCV_CSR_REGISTERS`, to be composed with `highLowToBigint` for the same reason. The
+     * `cycle` and `instret` counters are settled first, so they count every instruction executed
+     * so far.
+     */
+    getControlAndStatusRegistersValues(): Int32Array;
+    /**
+     * Sets one control and status register, writing it directly and recording no undo entry.
+     * Writing `fflags` or `frm` updates `fcsr`, and writing a counter such as `cycle` is allowed
+     * here even though the program cannot write it.
+     * @param index Position in `RISCV_CSR_REGISTERS`. Must be a whole number from 0 to 16;
+     * anything else throws.
+     */
+    setControlAndStatusRegisterValue(index: number, high: number, low: number): void;
     /**
      * Gets the undo stack.
      * @returns An array of `JsBackStep` objects representing the history of the simulation.
@@ -611,5 +662,11 @@ declare function makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string): J
  */
 declare function initializeRISCV(): void;
 declare function bigintToHighLow(value: bigint): [high: number, low: number];
+/**
+ * The inverse of `bigintToHighLow`: composes the unsigned 64 bit value of a high/low pair, as the
+ * register file getters return them. Both halves are taken unsigned, so a half the core hands over
+ * as a negative int still lands in the right place.
+ */
+declare function highLowToBigint(high: number, low: number): bigint;
 
-export { BackStepAction, ConfirmResult, DialogType, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, makeRiscVFromFiles, registerHandlers, unimplementedHandler };
+export { BackStepAction, ConfirmResult, type CsrRegisterName, DialogType, type FloatingPointRegisterName, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_CSR_REGISTERS, RISCV_FLOATING_POINT_REGISTERS, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, highLowToBigint, makeRiscVFromFiles, registerHandlers, unimplementedHandler };

package/dist/index.d.ts

@@ -350,6 +350,20 @@ declare enum RISCVRegisters {
 }
 type RegisterName = keyof typeof RISCVRegisters;
 declare const RISCV_REGISTERS: RegisterName[];
+/**
+ * The floating point registers, in the order `getFloatingPointRegistersValues` returns them, which
+ * is the order the core holds them in: register number 0 to 31, spelled as RARS spells them.
+ */
+declare const RISCV_FLOATING_POINT_REGISTERS: readonly ["ft0", "ft1", "ft2", "ft3", "ft4", "ft5", "ft6", "ft7", "fs0", "fs1", "fa0", "fa1", "fa2", "fa3", "fa4", "fa5", "fa6", "fa7", "fs2", "fs3", "fs4", "fs5", "fs6", "fs7", "fs8", "fs9", "fs10", "fs11", "ft8", "ft9", "ft10", "ft11"];
+type FloatingPointRegisterName = typeof RISCV_FLOATING_POINT_REGISTERS[number];
+/**
+ * The control and status registers the core implements, in the order
+ * `getControlAndStatusRegistersValues` returns them. `fflags` and `frm` are windows onto `fcsr`,
+ * and `cycleh`, `timeh` and `instreth` are the high halves of `cycle`, `time` and `instret`, so
+ * those pairs always agree.
+ */
+declare const RISCV_CSR_REGISTERS: readonly ["ustatus", "fflags", "frm", "fcsr", "uie", "utvec", "uscratch", "uepc", "ucause", "utval", "uip", "cycle", "time", "instret", "cycleh", "timeh", "instreth"];
+type CsrRegisterName = typeof RISCV_CSR_REGISTERS[number];
 type HandlerName = keyof HandlerMap;
 /**
  * A handler may return its result directly, or a promise of it. When a handler returns a promise
@@ -386,10 +400,6 @@ interface JsRiscV {
      * it settles once that handler and the rest of the instruction have finished.
      */
     step(): Promise<StopReason>;
-    /**
-     * Gets the 8 condition flags.
-     */
-    getConditionFlags(): number[];
     /**
      * Sets the size of the undo stack, must be called before assembling the program.
      * @param size
@@ -505,6 +515,47 @@ interface JsRiscV {
      * @returns An array containing the register values in long format. The order of the values is implementation defined.
      */
     getRegistersValuesLong(): string[];
+    /**
+     * Gets every floating point register as a high/low pair of 32 bit halves: element `2 * i` is
+     * the high half of register `i` and `2 * i + 1` its low half, so the array holds 64 numbers.
+     * The registers are in `RISCV_FLOATING_POINT_REGISTERS` order, and both halves matter on both
+     * targets: the file is 64 bit wide even on RV32, where a single is NaN-boxed into it (its high
+     * half is `0xFFFFFFFF`).
+     *
+     * The core hands this over as an `Int32Array` of signed 32 bit halves, so a half with its top
+     * bit set reads back negative: compose each pair with `highLowToBigint`, which takes both
+     * halves unsigned, rather than mapping `>>> 0` over the array (a typed array's `map` truncates
+     * the result back to int32, handing you the negative value again).
+     *
+     * Pairs rather than decimal strings because this is read on every panel refresh, and a 64 bit
+     * conversion per register is the kind of work that costs in the compiled core.
+     */
+    getFloatingPointRegistersValues(): Int32Array;
+    /**
+     * Sets one floating point register, writing it directly: no undo entry is recorded, because
+     * presetting a register from the host is not something the program did. Split the value with
+     * `bigintToHighLow`, and NaN-box a single yourself (`0xFFFFFFFFn << 32n | bits`) if that is
+     * what you mean.
+     * @param index Position in `RISCV_FLOATING_POINT_REGISTERS`. Must be a whole number from 0 to
+     * 31; anything else throws.
+     */
+    setFloatingPointRegisterValue(index: number, high: number, low: number): void;
+    /**
+     * Gets every control and status register as a high/low pair, in the same shape as
+     * `getFloatingPointRegistersValues`: an `Int32Array` of 34 signed halves for the 17 registers
+     * of `RISCV_CSR_REGISTERS`, to be composed with `highLowToBigint` for the same reason. The
+     * `cycle` and `instret` counters are settled first, so they count every instruction executed
+     * so far.
+     */
+    getControlAndStatusRegistersValues(): Int32Array;
+    /**
+     * Sets one control and status register, writing it directly and recording no undo entry.
+     * Writing `fflags` or `frm` updates `fcsr`, and writing a counter such as `cycle` is allowed
+     * here even though the program cannot write it.
+     * @param index Position in `RISCV_CSR_REGISTERS`. Must be a whole number from 0 to 16;
+     * anything else throws.
+     */
+    setControlAndStatusRegisterValue(index: number, high: number, low: number): void;
     /**
      * Gets the undo stack.
      * @returns An array of `JsBackStep` objects representing the history of the simulation.
@@ -611,5 +662,11 @@ declare function makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string): J
  */
 declare function initializeRISCV(): void;
 declare function bigintToHighLow(value: bigint): [high: number, low: number];
+/**
+ * The inverse of `bigintToHighLow`: composes the unsigned 64 bit value of a high/low pair, as the
+ * register file getters return them. Both halves are taken unsigned, so a half the core hands over
+ * as a negative int still lands in the right place.
+ */
+declare function highLowToBigint(high: number, low: number): bigint;
 
-export { BackStepAction, ConfirmResult, DialogType, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, makeRiscVFromFiles, registerHandlers, unimplementedHandler };
+export { BackStepAction, ConfirmResult, type CsrRegisterName, DialogType, type FloatingPointRegisterName, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_CSR_REGISTERS, RISCV_FLOATING_POINT_REGISTERS, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, highLowToBigint, makeRiscVFromFiles, registerHandlers, unimplementedHandler };