Merge pull request #1 from dark-tree/verilog-project-setup

core: Project setup and configuration, with a basic flip-flop example.

Author: mnurczynski

README.md

@@ -0,0 +1,15 @@
+# microarch
+
+**microarch** is a minimalistic, 8-bit, extensible, RISC, Harvard, load-store computer architecture intended for small low-power (or power constrained) microcontrollers.
+
+It offers 8-bit data address space and up to 16-bit instruction address space, allowing for up to 256 bytes of directly addressable data memory and up to 64kB of directly addressable program memory.
+
+The microarch processor has 8 registers available to the programmer with a powerful, unique register addressing system.
+
+
+##### Navigation
+
+- ```README.md``` - You are here.
+- ```LICENSE``` - License in place for the project.
+- ```microarch-ISA.pdf``` - Full ISA documentation for the architecture.
+- ```base-core/``` - WORK IN PROGRESS: A Verilog design of an example MicroArch core, with a Verilator/SystemC testbench (this part of the project has its own readme file).

base-core/.gitignore

@@ -0,0 +1,2 @@
+obj_dir/*
+tracedump/*

base-core/Makefile

@@ -0,0 +1,49 @@
+
+VERILOG_DESIGN_FILES = \
+	design/top.v				\
+	design/flip_flop.v
+
+default: run
+
+clean:
+	@echo "-- Cleaning build directories --"
+	rm -rf obj_dir/*
+	rm -rf tracedump/*
+
+waves:
+	@echo "Launching GTK waveform visualizer"
+	flatpak run io.github.gtkwave.GTKWave
+
+run: build_main
+	@echo "-- Running the microarch BaseCore SystemC main testbanch simulation --"
+	@echo "Running the simulation..."
+	obj_dir/Vtop +trace
+	@echo "Launching GTK waveform visualizer"
+	flatpak run io.github.gtkwave.GTKWave tracedump/traces.fst
+
+unit_tests: build_tests
+	@echo "-- Running the microarch BaseCore SystemC unit tests --"
+	@echo "Running the simulation..."
+	obj_dir/Vtop +trace
+
+build_main: verilate_main
+	@echo "-- Building microarch BaseCore testbench and verilated design --"
+	@echo "Building from generated Makefile..."
+	make -j -C obj_dir -f Vtop.mk
+
+build_tests: verilate_tests
+	@echo "-- Building microarch BaseCore testbench and verilated design --"
+	@echo "Building from generated Makefile..."
+	make -j -C obj_dir -f Vtop.mk
+
+verilate_main:
+	@echo "-- Verilating microarch BaseCore design simulation --"
+	@echo "Generating object files..."
+	@echo "Generating Makefile..."
+	verilator -sc -exe -Wall --trace-fst $(VERILOG_DESIGN_FILES) --top top testbench/sc_main.cpp
+
+verilate_tests:
+	@echo "-- Verilating microarch BaseCore tests --"
+	@echo "Generating object files..."
+	@echo "Generating Makefile..."
+	verilator -sc -exe -Wall --trace-fst $(VERILOG_DESIGN_FILES) --top top testbench/sc_unit_tests.cpp

base-core/README.md

@@ -0,0 +1,101 @@
+# microarch BaseCore
+
+**BaseCore** is a simple CPU core implementing the **microarch** ISA, designed in Verilog, with a testbench based on Verilator and SystemC.
+
+
+##### Navigation
+
+- ```README.md``` - You are here.
+- ```Makefile``` - Build script for the project. See the **Building and running the testbench** section for details.
+- ```tracedump/``` - Directory for trace files from testbench simulations in FST format (can be opened with GTKWave). NOTE: Trace files will only appear in the directory after building and running the testbench - they are not included in the git repository.
+  - ```traces.fst``` - Trace file from the main testbench simulation.
+  - ```traces_<module_name>_<test_name>.fst``` - Trace file from last execution of a specific test case.
+- ```obj_dir/``` - Directory for temporary build files.
+- ```design/``` - Directory for Verilog design files of the core itself.
+  - ```top.v``` - Top Verilog module.
+  - ```flip_flop.v``` - A simple D flip-flop design, used to test the testbench.
+- ```testbench``` - SystemC testbench for testing the core.
+  - ```sc_main.cpp``` - Main testbench simulation - for ad-hoc development and testing of modules.
+  - ```sc_unit_tests.cpp``` - A set of unit tests for Verilog modules.
+  - ```test_runner.h``` - A simple system for running unit tests, used by ```sc_unit_tests.cpp```.
+
+##### Building and running the testbench
+
+###### Dependencies:
+
+- ```verilator```
+- ```SystemC library from Accellera```
+- ```make```
+- ```GTKWave FlatPak package```
+- ```g++ compiler```
+
+###### Cleaning the build directory:
+
+If something does not work, try a clean build by running ```make clean```
+
+Note: this will delete all trace files from ```tracedump/```
+
+###### Running the main simulation:
+
+The main testbench simulation source is located in the  ```sc_main.cpp``` file (that's where you can manipulate the inputs).
+To start it, execute:
+
+```make run```
+
+After the simulation completes, a ```GTKWave``` window will open (displaying traces, ie. a timeline of value changes on all inputs/outputs of the design).  Note: To see the traces you need to select the module from a drop-down menu on the left and then select I/O ports by double-clicking them.
+
+###### Running unit tests:
+
+To run the unit tests, execute:
+
+```make unit_tests```
+
+Information will be printed, on which tests passed and which did not pass.
+
+You can view trace files generated by the tests with ```GTKWave```.
+To quickly launch ```GTKWave``` run:
+
+```make waves```
+
+Code for unit tests is located in ```sc_unit_tests.cpp``` file.
+
+You can write your own test file. **Test file format:**
+
+```
+// Include the unit test system
+#include "test_runner.h"
+
+TESTS;
+
+  // Declaring a test:
+  TEST(module1, my_test)
+      // Creating a signal:
+      SET_SIGNAL(signal_name);
+      // Optioonally you may also create a clock - with period and delay in given in nanoseconds
+      SET_CLOCK(my_clock, 10, 3);
+      //Make sure, that clock and signal names match names from the Verilog module
+  START_SIMULATION;
+      // Assign binary value to a signal.
+      signal_name = true;
+      // Run simulation for a given number of nanoseconds.
+      STEP(4);
+      // Assert value of the signal (if the assertion fails, the test will be marked as failed and failed assertion will be printed
+      signal_assert(true, signal_name, "my nice assertion");
+  END_SIMULATION;
+
+ // Declaring another test:
+  TEST(module1, another_test)
+      // Initialize signals/clocks here
+  START_SIMULATION;
+      // Run the test here
+  END_SIMULATION;
+
+ // Declaring another test for a different module
+  TEST(module2, another_test)
+      // Initialize signals/clocks here
+  START_SIMULATION;
+      // Run the test here
+  END_SIMULATION;
+
+END_TESTS;
+```

base-core/design/flip_flop.v

@@ -0,0 +1,16 @@
+module flip_flop
+	(
+		input clk,
+		input reset,
+		input D,
+		output reg Q
+	);
+
+	always @(posedge clk or posedge reset)
+	begin
+		if(reset == 1'b1)
+			Q <= '0;
+		else
+			Q <= D;
+	end
+endmodule

base-core/design/top.v

@@ -0,0 +1,19 @@
+module top
+	(
+		input clk,
+		input reset,
+		input D,
+		output reg Q
+	);
+
+	always @(posedge clk or posedge reset)
+	begin
+		if(reset == 1'b1)
+			Q <= '0;
+		else
+			Q <= D; 	
+	end
+endmodule
+		
+
+	 

base-core/testbench/sc_main.cpp

@@ -0,0 +1,72 @@
+#include <systemc>
+#include <verilated.h>
+#include <verilated_fst_sc.h>
+#include <memory>
+
+
+
+#include "Vtop.h"
+
+using namespace sc_core;
+using namespace sc_dt;
+
+
+int sc_main(int argc, char* argv[]) {
+		Verilated::debug(0);			//Debug level
+		Verilated::traceEverOn(true);		//We need to tell verilator, that tracing will be used
+		Verilated::randReset(2); 		//Reset randomization policy
+		Verilated::commandArgs(argc, argv); 	//Passing command args (required)
+
+		sc_clock clk{
+				"clk",	// Name
+				10,			// Period
+				SC_NS,	// Unit of the period
+				0.5,		// Duty cycle
+				3,			// Delay (time until first edge)
+				SC_NS,	// Unit of delay
+				true		// Is the rising edge first
+		};
+
+		const std::unique_ptr<Vtop> top{new Vtop{"top"}};
+		sc_signal<bool> reset;
+		sc_signal<bool> D;
+		sc_signal<bool> Q;
+
+
+		top->clk(clk);
+		top->reset(reset);
+		top->Q(Q);
+		top->D(D);
+
+		sc_start(SC_ZERO_TIME);
+
+		auto tfp = new VerilatedFstSc;
+		top->trace(tfp, 99); 	//Telling SystemC to trace up to 99 levels of hierarchy.
+		tfp->open("tracedump/traces.fst");
+
+		for(int i = 0; i<100;i++)
+		{
+				if (sc_time_stamp() > sc_time(28, SC_NS) && sc_time_stamp() < sc_time(30, SC_NS)) {
+		            		reset = true;
+		        	} else {
+		            		reset = false;
+		        	}
+				if (sc_time_stamp() > sc_time(15, SC_NS) && sc_time_stamp() < sc_time(50, SC_NS)) {
+		            		D = true;
+		        	} else {
+		            		D = false;
+		        	}
+
+
+				sc_start(1, SC_NS);
+
+
+		}
+
+		top->final();
+
+		tfp->close();
+
+		return 0;
+
+}

base-core/testbench/sc_unit_tests.cpp

@@ -0,0 +1,97 @@
+#include "test_runner.h"
+
+TESTS;
+
+    TEST(top, test)
+        SET_CLOCK(clk, 10, 3);
+        SET_SIGNAL(reset);
+        SET_SIGNAL(D);
+        SET_SIGNAL(Q);
+    START_SIMULATION;
+        D = false;
+        reset = false;
+        STEP(10)
+        reset = true;
+        STEP(1)
+        reset = false;
+        STEP(10)
+        assert_signal(false, Q, "reset");
+        D = true;
+        for(int i = 0; i<5;i++)
+        {
+            STEP(1)
+            if(clk == false)
+            {
+                assert_signal(false, Q, "bef edge");
+            }
+            else
+            {
+                assert_signal(true, Q, "after edge");
+            }
+        }
+    END_SIMULATION;
+
+
+    TEST(flip_flop, test_manual_clock)
+        SET_SIGNAL(clk)
+        SET_SIGNAL(reset);
+        SET_SIGNAL(D);
+        SET_SIGNAL(Q);
+    START_SIMULATION;
+        clk = false;
+        reset = false;
+
+        D = true;
+        STEP(10)
+        assert_signal(false, Q, "bef edge 1");
+        clk = true;
+        STEP(10)
+        clk = false;
+        assert_signal(true, Q, "after edge 1");
+
+        reset = true;
+        STEP(1)
+        reset = false;
+        STEP(10)
+        assert_signal(false, Q, "reset");
+        STEP(10)
+        assert_signal(false, Q, "bef edge 2");
+        clk = true;
+        STEP(1)
+        assert_signal(true, Q, "after edge 2");
+        D = false;
+
+    END_SIMULATION;
+
+
+    TEST(flip_flop, test)
+        SET_CLOCK(clk, 10, 3);
+        SET_SIGNAL(reset);
+        SET_SIGNAL(D);
+        SET_SIGNAL(Q);
+    START_SIMULATION;
+        D = false;
+        reset = false;
+        STEP(10)
+        reset = true;
+        STEP(1)
+        reset = false;
+        STEP(10)
+        assert_signal(false, Q, "reset");
+        D = true;
+        for(int i = 0; i<5;i++)
+        {
+            STEP(1)
+            if(clk == false)
+            {
+                assert_signal(false, Q, "bef edge");
+            }
+            else
+            {
+                assert_signal(true, Q, "after edge");
+            }
+        }
+    END_SIMULATION;
+
+
+END_TESTS;