Add docker command to README.md and modify simulation files so they a…

…void features we do not have available.

.gitignore

@@ -1,3 +1,4 @@
 examples/**/obj_dir
 examples/**/*.txt
 examples/**/*.vcd
+.ccache

README.md

@@ -2,6 +2,24 @@
 
 The main contribution of this project is the `verilator.mk` makefile. Include it in your own project in the same manner as seen in the examples.
 
+# Usage
+
+[Docker](https://www.docker.com/) should be used to run the examples. Run the command
+
+`docker run -e CCACHE_DIR=/work/.ccache -ti -v $(pwd):/work --entrypoint bash --hostname verilator-env verilator/verilator:4.038`
+
+or a similar one to enter the container. It should be run from the root of this repository. The first time this is run, it will download a docker image which gives information on which programs and their versions to use. After that, it will jump into the image.
+
+The purpose of this is to ensure we always run the same programs for our code. In the case of `verilator`, it is not very backward-compatible between versions, so Docker is very useful here.
+
+Inside the docker environment, run `make` to run the tests.
+
+## The docker command explained
+
+1. `-e CCACHE_DIR=/work/.ccache`: Verilator uses ccache which defaults to a location outside the container. We override it with an environment variable here.
+2. `--entrypoint bash`: Stops Docker from running verilator once and exiting.
+3. `verilator/verilator:4.038`: The Verilator version we want to use.
+
 # Examples
 
 The examples show how Verilator can be used to simualate a Verilog circuit. Feel free to add more examples and tests for them.

examples/add/sim.cpp

@@ -6,15 +6,14 @@
 #include <iostream>
 
 int main(int argc, char** argv) {
-    VerilatedContext* contextp = new VerilatedContext;
-    contextp->commandArgs(argc, argv);
-    VAdd* top = new VAdd{contextp};
+    VAdd* top = new VAdd;
+    Verilated::commandArgs(argc, argv);
 
     int stimuli_a[] = { 2, -1, 1, -6 };
     int stimuli_b[] = { 4,  5, 2,  7 }; 
 
     for (int i = 0; i < sizeof(stimuli_a) / sizeof(stimuli_a[0]); i++) {
-        if (contextp->gotFinish()) break;
+        if (Verilated::gotFinish()) break;
 
         top->a = stimuli_a[i];
         top->b = stimuli_b[i];
@@ -25,6 +24,5 @@ int main(int argc, char** argv) {
     }
 
     delete top;
-    delete contextp;
     return 0;
 }

examples/and/sim.cpp

@@ -9,9 +9,8 @@
 #include <iostream>
 
 int main(int argc, char** argv) {
-    VerilatedContext* contextp = new VerilatedContext;
-    contextp->commandArgs(argc, argv);
-    VAnd* top = new VAnd{contextp};
+    VAnd* top = new VAnd;
+    Verilated::commandArgs(argc, argv);
 
     // For waveform generation
     unsigned long tickcount = 0;
@@ -27,7 +26,7 @@ int main(int argc, char** argv) {
     bool stimuli_b[] = { false, true, false, true }; 
 
     for (int i = 0; i < sizeof(stimuli_a) / sizeof(stimuli_a[0]); i++) {
-        if (contextp->gotFinish()) break;
+        if (Verilated::gotFinish()) break;
 
         top->a = stimuli_a[i];
         top->b = stimuli_b[i];
@@ -47,6 +46,5 @@ int main(int argc, char** argv) {
     delete trace;
 
     delete top;
-    delete contextp;
     return 0;
 }

examples/doublesub/sim.cpp

@@ -7,9 +7,8 @@
 int get_stimuli(std::string filename, int *data);
 
 int main(int argc, char** argv) {
-    VerilatedContext* contextp = new VerilatedContext;
-    contextp->commandArgs(argc, argv);
-    VDoubleSub* top = new VDoubleSub{contextp};
+    VDoubleSub* top = new VDoubleSub;
+    Verilated::commandArgs(argc, argv);
 
     int *operands = new int[200];
     int noperands = get_stimuli(std::string{"operands.data"}, operands);
@@ -29,6 +28,5 @@ int main(int argc, char** argv) {
 
 
     delete top;
-    delete contextp;
     return 0;
 }

examples/hierarchy/delay/main.cpp

@@ -5,9 +5,8 @@
 #include <iostream>
 
 int main(int argc, char** argv) {
-    VerilatedContext* contextp = new VerilatedContext;
-    contextp->commandArgs(argc, argv);
-    VDelay* top = new VDelay{contextp};
+    VDelay* top = new VDelay;
+    Verilated::commandArgs(argc, argv);
 
     int data_in = 0x66234223;
 
@@ -40,6 +39,5 @@ int main(int argc, char** argv) {
     assert(top->delayed_data == data_in);
 
     delete top;
-    delete contextp;
     return 0;
 }

examples/hierarchy/main.cpp

@@ -5,9 +5,8 @@
 #include <iostream>
 
 int main(int argc, char** argv) {
-    VerilatedContext* contextp = new VerilatedContext;
-    contextp->commandArgs(argc, argv);
-    VHierarchy* top = new VHierarchy{contextp};
+    VHierarchy* top = new VHierarchy;
+    Verilated::commandArgs(argc, argv);
 
     int data_in = 0x66234223;
     int subtract = 22;
@@ -44,6 +43,5 @@ int main(int argc, char** argv) {
     assert(top->data_out == (data_in - subtract));
 
     delete top;
-    delete contextp;
     return 0;
 }

verilator.mk

@@ -13,8 +13,8 @@ lint: $(SOURCES)
 $(VERILATOR_EXE): lint | $(SOURCES)
 	verilator $(VERILATOR_ARGS) $(SIMFILES) $(SOURCES) > /dev/null
 
+# https://stackoverflow.com/questions/17757039/equivalent-of-pipefail-in-dash-shell
 run: $(VERILATOR_EXE)
-	# https://stackoverflow.com/questions/17757039/equivalent-of-pipefail-in-dash-shell
 	@mkfifo named_pipe
 	@tee output.txt < named_pipe &
 	@./$(VERILATOR_EXE) > named_pipe; ./$(PARSER) $(PROJECT_NAME) $$? output.txt