Celox

English

Japanese

English

Japanese

Appearance

@celox-sim/celox / index / Simulator

Class: Simulator<P> ​

Defined in: packages/celox/src/simulator.ts:71

Type Parameters ​

P ​

P = Record<string, unknown>

Accessors ​

dut ​

Get Signature ​

get dut(): P

Defined in: packages/celox/src/simulator.ts:432

The DUT accessor object — read/write ports as plain properties.

Returns ​

P

warnings ​

Get Signature ​

get warnings(): readonly string[]

Defined in: packages/celox/src/simulator.ts:437

Analyzer warnings emitted during compilation.

Returns ​

readonly string[]

Methods ​

checkpoint() ​

checkpoint(): SimulatorCheckpoint

Defined in: packages/celox/src/simulator.ts:558

Save the design state.

The checkpoint can be restored any number of times, into this simulator or into another one created from the same design.

Returns ​

SimulatorCheckpoint

dispose() ​

dispose(): void

Defined in: packages/celox/src/simulator.ts:626

Release native resources.

Returns ​

void

dump() ​

dump(timestamp): void

Defined in: packages/celox/src/simulator.ts:547

Write current signal values to VCD at the given timestamp.

Parameters ​

timestamp ​

number

Returns ​

void

event() ​

event(name): EventHandle

Defined in: packages/celox/src/simulator.ts:514

Resolve an event name to a handle for use with tick().

Parameters ​

name ​

string

Returns ​

EventHandle

fourState() ​

fourState(portName): FourStateValue

Defined in: packages/celox/src/simulator.ts:530

Read the raw 4-state (value + mask) pair for the named port.

Like an output read through dut, this evaluates combinational logic first when inputs changed since the last evaluation.

Parameters ​

portName ​

string

Returns ​

FourStateValue

loadState() ​

loadState(bytes): void

Defined in: packages/celox/src/simulator.ts:616

Load state file bytes saved by saveState(), matching signals by path.

Throws without changing anything if a register, memory or input of this design is missing from the file or has another width.

Parameters ​

bytes ​

Uint8Array

Returns ​

void

restore() ​

restore(checkpoint): void

Defined in: packages/celox/src/simulator.ts:572

Return to the state saved in checkpoint.

Throws if the checkpoint comes from another design. VCD output records the restored values as changes at the next dump().

Parameters ​

checkpoint ​

SimulatorCheckpoint

Returns ​

void

saveState() ​

saveState(): Uint8Array

Defined in: packages/celox/src/simulator.ts:600

Save the value of every state object, by signal path, as state file bytes. Unlike a checkpoint, a state file loads into simulators built with another backend or optimization level, and can be written to disk.

Returns ​

Uint8Array

switchVcd() ​

switchVcd(path): void

Defined in: packages/celox/src/simulator.ts:587

Finish the current VCD file and continue the waveform in a new file at path, whose timestamps start over. Use it to record a simulator rewound by restore() or loadState(): dump() rejects a timestamp earlier than the last one it wrote.

Parameters ​

path ​

string

Returns ​

void

tick() ​

Call Signature ​

tick(event?, count?): void

Defined in: packages/celox/src/simulator.ts:460

Trigger a clock edge.

A single numeric argument is the tick count for the default event. When a second argument is not undefined, a numeric first argument is treated as a raw event ID. Therefore, use tick(id, 1) to tick a raw event ID once. Prefer an EventHandle returned by this.event() when selecting an event. tick(undefined, count) ticks the default event.

Parameters ​
event? ​

number | EventHandle

Optional event handle or known raw event ID. If omitted, ticks the first (default) event.

count? ​

number

Number of ticks as an unsigned 32-bit integer. Zero evaluates pending combinational logic without triggering an event. Default: 1.

Returns ​

void

Throws ​

RangeError if the count or selected event ID is invalid, or if the selected event ID is not known to this Simulator.

Throws ​

Error if a positive count uses the default event but the Simulator has no events.

Call Signature ​

tick(count?): void

Defined in: packages/celox/src/simulator.ts:461

Trigger a clock edge.

A single numeric argument is the tick count for the default event. When a second argument is not undefined, a numeric first argument is treated as a raw event ID. Therefore, use tick(id, 1) to tick a raw event ID once. Prefer an EventHandle returned by this.event() when selecting an event. tick(undefined, count) ticks the default event.

Parameters ​
count? ​

number

Number of ticks as an unsigned 32-bit integer. Zero evaluates pending combinational logic without triggering an event. Default: 1.

Returns ​

void

Throws ​

RangeError if the count or selected event ID is invalid, or if the selected event ID is not known to this Simulator.

Throws ​

Error if a positive count uses the default event but the Simulator has no events.

create() ​

static create<P>(module, options?): Simulator<P>

Defined in: packages/celox/src/simulator.ts:112

Create a Simulator for the given module.

ts
import { Adder } from "./generated/Adder.js";
const sim = Simulator.create(Adder);

Type Parameters ​

P ​

P

Parameters ​

module ​

ModuleDefinition<P>

options? ​

SimulatorOptions & object

Returns ​

Simulator<P>

fromFrontendArtifact() ​

static fromFrontendArtifact<P>(artifactJson, options?): Simulator<P>

Defined in: packages/celox/src/simulator.ts:266

Create a Simulator from a versioned artifact emitted by an external frontend built with celox-frontend-sdk.

Type Parameters ​

P ​

P = Record<string, unknown>

Parameters ​

artifactJson ​

string

options? ​

SimulatorOptions & object

Returns ​

Simulator<P>

fromFrontendHandle() ​

static fromFrontendHandle<P>(raw, options?): Simulator<P>

Defined in: packages/celox/src/simulator.ts:299

Wrap a raw simulator handle returned by a frontend-owned native or WASM addon.

This is the adapter boundary for frontend packages. A frontend's public API can accept its own artifact type, call its native fromMyArtifact function, then pass the returned handle here. No Celox artifact JSON is involved.

Type Parameters ​

P ​

P = Record<string, unknown>

Parameters ​

raw ​

FrontendSimulatorHandle

options? ​

Pick<SimulatorOptions, "deadStorePolicy">

Returns ​

Simulator<P>

fromProject() ​

static fromProject<P>(projectPath, top, options?): Simulator<P>

Defined in: packages/celox/src/simulator.ts:359

Create a Simulator from a Veryl project directory.

Searches upward from projectPath for Veryl.toml, gathers all .veryl source files, and builds the simulator using the project's clock/reset settings.

ts
const sim = Simulator.fromProject<MyPorts>("./my-project", "Top");

Type Parameters ​

P ​

P = Record<string, unknown>

Parameters ​

projectPath ​

string

top ​

string

options? ​

SimulatorOptions & object

Returns ​

Simulator<P>

fromSource() ​

static fromSource<P>(source, top, options?): Simulator<P>

Defined in: packages/celox/src/simulator.ts:183

Create a Simulator directly from Veryl source code.

Automatically discovers ports from the NAPI layout — no ModuleDefinition needed.

ts
const sim = Simulator.fromSource<AdderPorts>(ADDER_SOURCE, "Adder");
sim.dut.a = 100;
sim.dut.b = 200;
sim.tick();
expect(sim.dut.sum).toBe(300);

Type Parameters ​

P ​

P = Record<string, unknown>

Parameters ​

source ​

string

top ​

string

options? ​

SimulatorOptions & object

Returns ​

Simulator<P>