Merge pull request #110 from POETSII/dt10-polite-sw-sim

POLite software simulation

.gitignore

@@ -0,0 +1,4 @@
+**/build/*
+*.o
+*.elf
+*.a

README.md

@@ -61,7 +61,8 @@ Released on 1 Jul 2020 and maintained in the
 * [F. Tinsel API](#f-tinsel-api)
 * [G. HostLink API](#g-hostlink-api)
 * [H. Limitations on RV32IMF](#h-limitations-on-rv32imf)
-* [I. Publications](#i-publications)
+* [I. Testing](#i-testing)
+* [J. Publications](#j-publications)
 
 ## 1. Overview
 
@@ -1356,6 +1357,47 @@ to deal with highly non-uniform fanouts (i.e. where some vertices have
 tiny fanouts and others have huge fanouts; this could be alleviated by
 adding fanout as a vertex weight for METIS partitioning).
 
+**Simulation**. There is a simple and partial functional simulation of the
+POLite framework in [apps/util/POLiteSWSim](apps/util/POLiteSWSim). This
+implements most of the common parts of the POLite `PGraph` and `PDevice` class,
+along with just enough `HostLink` to give a run-time API. Assuming you
+are using the default POLite makefile then it will be available for free.
+So if you are currently doing:
+```
+$ make all
+$ (cd build && ./run ARGS)
+```
+to run your application, you should be able to simulate using:
+```
+$ make sim
+$ (cd build && ./sim ARGS)
+```
+All the makefile does is include the `POLiteSW/include` directory
+ahead of the main `include/POLite` directory, so it overrides the
+"real" header files.
+
+Note that the simulator is intended to uncover errors, and so it models
+the fairly worst-case behaviour in terms of message delivery. In particular, it
+inserts exponentially distributed random delays between sends and corresponding
+receives, and so causes many messages to be delivered in a different order to
+the sending order.
+
+There are two environment parameters that will affect the run-time
+behaviour of the simulation:
+
+- `POLITE_SW_SIM_VERBOSITY` : Controls logging of simulation info to stderr. At 0 only
+   fatal errors are printed. For values larger than 0 increasing amounts of info are printed.
+   Default is 1, which prints progress information during simulation. Printing frequency
+   will slow down as the simulation takes longer.
+
+- `POLITE_SW_SIM_DELIVER_OUT_OF_ORDER` : Controls whether messages can be delayed and
+   delivered out of order in the simulation. By default this is "true", but if you set
+   it to "0" or "false" then you might find simulation a bit faster. Note that current
+   (0.8.3) hardware behaviour is somewhat in-between - messages can be delayed arbitrarily,
+   but for any (dst,src) pair the messages will be delivered in order. However, this was
+   not true in previous hardware, and may not be true in future hardware. Actually,
+   it is not true on current hardware for mixed unicast and multicast transmissions.
+
 ## A. DE5-Net Synthesis Report
 
 The default Tinsel configuration on a single DE5-Net board contains:
@@ -1925,7 +1967,35 @@ inerhit a number of limitations:
     See [Issue #54](https://github.com/POETSII/tinsel/issues/54)
     for more details.
 
-## I. Publications
+## I. Testing
+
+This repo contains (at least) the following automated self-test
+facilities:
+
+- [Instruction tests](tests/) - These test the basic instruction
+    execution capabiities of the tinsel hardware. To run, do:
+    ```
+    $ make -C tests
+    $ (cd tests && ./run)
+    ```
+    These tests work on any machine with Tinsel hardware, and if a test
+    fails then something is probably quite seriously wrong with configuration
+    or the hardware has been mis-built.  These tests (and indeed any
+    application) can also be run using the cycle-accurate hardware
+    simulator produced by the Bluespec compiler (`make sim` in the
+    `rtl` directory).  However, this simulator is *very* slow (even
+    when `config.py` is modified to use fewer cores per board).
+
+- [POLiteSWSim tests](apps/POLite/util/POLiteSWSim) - These test
+    the POLiteSWSim framework (software simulation of POLite apps),
+    and can be run using:
+    ```
+    $ apps/POLite/util/test_polite_sw_sim.sh
+    ```
+    These tests should work on any machine, regardless of whether there
+    is Tinsel hardware installed.
+
+## J. Publications
 
 * *Tinsel: a manythread overlay for FPGA clusters*, FPL 2019
   ([paper](https://www.repository.cam.ac.uk/handle/1810/294801))

apps/POLite/clocktree-async/Run.cpp

@@ -32,7 +32,8 @@ int main(int argc, char** argv)
   // Create POETS graph
   PGraph<ClockTreeDevice, ClockTreeState, None, ClockTreeMessage> graph;
   graph.mapVerticesToDRAM = true;
-  graph.mapInEdgesToDRAM = true;
+  graph.mapInEdgeHeadersToDRAM=true;
+  graph.mapInEdgeRestToDRAM=true;
   graph.mapOutEdgesToDRAM = true;
 
   // Number of devices in tree

apps/POLite/pressure-sync/Run.cpp

@@ -6,14 +6,18 @@
 #include <POLite.h>
 #include <sys/time.h>
 
-// Number of time steps
-#define T 1000
-
 // Volume dimensions
 #define D 40
 
-int main()
+int main(int argc, char *argv[])
 {
+  int T=1000;
+
+  if(argc>1){
+    T=atoi(argv[1]);
+    fprintf(stderr, "Setting T=%u\n", T);
+  }
+
   HostLink hostLink;
   PGraph<PressureDevice, PressureState, Dir, PressureMessage> graph;
   //graph.mapVerticesToDRAM = true;

apps/POLite/util/POLiteSWSim/include/HostLink.h

@@ -0,0 +1 @@
+#include "POLite.h"

apps/POLite/util/POLiteSWSim/include/POLite.h

@@ -0,0 +1,27 @@
+#ifndef POLiteSWSim_POLite_h
+#define POLiteSWSim_POLite_h
+
+// Everything in here is in namespace POLiteSWSim
+#include "POLite/PGraph.h"
+
+// We then explicitly being it out into the global namespace
+
+using POLiteSWSim::PGraph;
+using POLiteSWSim::PDevice;
+using POLiteSWSim::HostLink;
+using POLiteSWSim::PMessage;
+
+using POLiteSWSim::None;
+using POLiteSWSim::No;
+using POLiteSWSim::HostPin;
+using POLiteSWSim::PPin;
+using POLiteSWSim::Pin;
+using POLiteSWSim::PDeviceId;
+
+using namespace POLiteSWSim::config;
+
+// This is defined in tinsel-interface.h, and used in some apps.
+// Defined empty here for compatibility, but would be nice to get rid of it
+#define INLINE
+
+#endif