Emulator
niblick.emulator.Emulator implements the Voja4 CPU and a UART model for
tests and the debugger.
Command line
python3 -m niblick examples/hello.nbl --run
python3 -m niblick examples/hello.nbl --run --trace --trace-limit 20
python3 -m niblick examples/hello.nbl --run --trace-io --io-trace-limit 200
See Command-line reference for all run and dump options.
Python API
from niblick.emulator import Emulator
emu = Emulator()
emu.load_hex("examples/hello.hex")
steps = emu.run(max_steps=100000)
print(steps, emu.cycle_count, emu.elapsed_seconds)
print(bytes(emu.uart_tx))
Member |
Type |
Meaning |
|---|---|---|
|
method |
Load and validate a |
|
method |
Load a |
|
method |
Load 12-bit instruction words |
|
method |
Clear CPU state and RAM; keep the loaded program |
|
method |
Execute one instruction |
|
method |
Execute until halt or step limit; return step count |
|
method |
Request that |
|
method |
Set the 4-bit input port |
|
method |
Queue bytes for |
|
method |
Front-panel input |
|
method |
Record OUT/OUTB/IN/INB events |
|
method |
Return the left and right visible pages |
|
method |
Return a state snapshot |
|
|
4096 instruction words |
|
|
256 nibbles |
|
attributes |
CPU state |
|
|
UART byte buffers |
|
|
Sticky UART error state |
|
attributes |
Execution counters |
|
`list[IoTraceEvent] |
None` |
|
attribute |
Total events seen |
reset() clears RAM and control state; the loaded program is retained.
Model
Item |
Behavior |
|---|---|
Data RAM |
256 nibbles; registers are |
Program |
4096 12-bit words |
UART TX |
Bytes written through |
UART RX |
Byte queue read through |
|
Queue length, saturated at 15 |
Buttons |
|
|
Deterministic 16-bit LCG |
|
Approximated from instruction count |
|
Writing 0 halts the CPU |
Display |
Visible page pair |
Counters |
Instruction and cycle counts, estimated time |
I/O trace |
OUT, OUTB, IN, INB events |
The emulator does not model LED brightness, real-time clock accuracy, or electrical behavior.
I/O tracing
emu = Emulator()
emu.load_hex("driver.hex")
emu.set_input(0)
emu.trace_io(limit=2000)
emu.run(5_000_000)
for event in emu.io_trace:
print(event.kind, hex(event.address), event.bit, event.before, event.after)
Events have kind (write, bit, or read), address, before, after,
pc, step, and an optional bit.
Step limits
run stops only on .halted or the step limit. Intentional JR -1 loops are
not auto-detected.