sim: split into base, core, and engines.
authorwhitequark <whitequark@whitequark.org>
Thu, 27 Aug 2020 10:17:02 +0000 (10:17 +0000)
committerLuke Kenneth Casson Leighton <lkcl@lkcl.net>
Fri, 31 Dec 2021 15:11:24 +0000 (15:11 +0000)
commitd33779cabee53973330d458c27491898cb74a9e3
tree154baaa291c9679bbcac282de6baf3cd31f93dad
parentd9daa8abc61ccff70eeaceeebca5afd39d2aae06
sim: split into base, core, and engines.

Before this commit, each simulation engine (which is only pysim at
the moment, but also cxxsim soon) was a subclass of SimulatorCore,
and every simulation engine module would essentially duplicate
the complete structure of a simulator, with code partially shared.

This was a really bad idea: it was inconvenient to use, with
downstream code having to branch between e.g. PySettle and CxxSettle;
it had no well-defined external interface; it had multiple virtually
identical entry points; and it had no separation between simulation
algorithms and glue code.

This commit completely rearranges simulation code.
  1. sim._base defines internal simulation interfaces. The clarity of
     these internal interfaces is important because simulation
     engines mix and match components to provide a consistent API
     regardless of the chosen engine.
  2. sim.core defines the external simulation interface: the commands
     and the simulator facade. The facade provides a single entry
     point and, when possible, validates or lowers user input.
     It also imports built-in simulation engines by their symbolic
     name, avoiding eager imports of pyvcd or ctypes.
  3. sim.xxxsim (currently, only sim.pysim) defines the simulator
     implementation: time and state management, process scheduling,
     and waveform dumping.

The new simulator structure has none of the downsides of the old one.

See #324.
19 files changed:
examples/basic/ctr_en.py
nmigen/back/pysim.py
nmigen/compat/sim/__init__.py
nmigen/sim/__init__.py
nmigen/sim/_base.py [new file with mode: 0644]
nmigen/sim/_cmds.py [deleted file]
nmigen/sim/_core.py [deleted file]
nmigen/sim/_pyclock.py
nmigen/sim/_pycoro.py
nmigen/sim/_pyrtl.py
nmigen/sim/core.py [new file with mode: 0644]
nmigen/sim/pysim.py
nmigen/vendor/lattice_machxo2.py
tests/test_lib_cdc.py
tests/test_lib_coding.py
tests/test_lib_fifo.py
tests/test_lib_io.py
tests/test_lib_scheduler.py
tests/test_sim.py