# OTBNSim - OTBN Simulation Software

`OTBNSim` class represents a simulator that models the whole OTBN block.
Therefore it includes abstract models for the the state of the core, its memory modules, and also the register modules.
It has methods for starting the execution, cycle-accurate simulation tracing, and for injecting errors and reacting to those errors with a secure wipe.
As explained in the overall [OTBN DV documentation](../README.md), this simulator is driven essentially from the SystemVerilog model of the OTBN module.

The simulator works in a step-by-step fashion and it has multiple methods to apply external stimuli to OTBN.
In a typical run without errors, the ISS does the following:
 1. Decode the program on the path given by `iss_wrapper.cc` by the `decode_file` method in `decode.py`.
 2. Load the decoded program to a local list in `sim.py`.
 3. With each `step` command from the SystemVerilog side, update the simulated state of the core (`state.py`), registers (`wsr.py`, `csr.py` and `gpr.py`) and data memory (`dmem.py`).
 4. Once the step is done, pass the generated trace to `iss_wrapper.cc`, which to then passes it on to `OTBNTraceChecker`.

## Co-Simulation with RTL
For co-simulation of RTL and ISS, the `otbn_tracer` module logs state changes of the RTL, and the ISS logs state changes of the Python model.
Trace entries from the simulated core (aka. from RTL) appear as a result of DPI callbacks while ISS trace entries appear in the trace checker through `ISSWrapper` using `OnIssTrace` method after sending a step command to `OTBNSim`.
To check correct behaviour, the two separate logs generated by the model and the RTL are compared.
For more information about how OTBN RTL produces traces see the [Tracer README](../tracer/README.md).
To see the C++ program that compares both traces, check the method `otbn_trace_checker.cc` in `../model/otbn_trace_entry`.