Merge pull request google#462 from antmicro/aj-add-renode-tutorial

Add Renode documentation
antmicro · Feb 11, 2022 · 6a17349 · 6a17349
2 parents 388070b + 3100e8f
commit 6a17349
Show file tree

Hide file tree

Showing 8 changed files with 348 additions and 21 deletions.
diff --git a/common/interact.expect b/common/interact.expect
@@ -1,6 +1,7 @@
 #!/usr/bin/expect -f
 #
-# Choose simulation mode by making the first arg "s" (no dash).   
+# Choose Verilator simulation mode by making the first arg "s" (no dash)
+#  or Renode simulation mode by making the first arg "r" (no dash).
 #  Then no other options, just the menu choices.
 #
 # For non-simulation (Arty) mode:

diff --git a/common/renode-verilator-integration/CMakeLists.txt b/common/renode-verilator-integration/CMakeLists.txt
@@ -12,6 +12,11 @@ if(TRACE_DEPTH_VAL)
 endif()
 set(VERI_LIB_ARGS ${ENABLE_TRACE} ${TRACE_DEPTH} -Wno-WIDTH -Wno-CASEINCOMPLETE -Wno-CASEOVERLAP)
 
+# Used by 'sim_main.cpp'.
+if(ENABLE_TRACE AND TRACE_FILEPATH)
+  add_definitions(-DTRACE_FILEPATH="${TRACE_FILEPATH}")
+endif()
+
 find_package(verilator)
 
 file(GLOB_RECURSE RENODE_SOURCES ${VIL_DIR}/cfu.cpp ${VIL_DIR}/renode_cfu.cpp)

diff --git a/common/renode-verilator-integration/sim_main.cpp b/common/renode-verilator-integration/sim_main.cpp
@@ -11,17 +11,28 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <stdint.h>
-#if VM_TRACE
+
+#if VM_TRACE_VCD
 # include <verilated_vcd_c.h>
+# define VERILATED_DUMP VerilatedVcdC
+# define DEF_TRACE_FILEPATH "simx.vcd"
+#elif VM_TRACE_FST
+# include <verilated_fst_c.h>
+# define VERILATED_DUMP VerilatedFstC
+# define DEF_TRACE_FILEPATH "simx.fst"
 #endif
+
 #include "src/renode_cfu.h"
 #include "src/buses/cfu.h"
 
 RenodeAgent *cfu;
 Vcfu *top = new Vcfu;
-VerilatedVcdC *tfp;
 vluint64_t main_time = 0;
 
+#if VM_TRACE
+VERILATED_DUMP *tfp;
+#endif
+
 void eval() {
 #if VM_TRACE
     main_time++;
@@ -60,10 +71,15 @@ RenodeAgent *Init() {
 
 #if VM_TRACE
     Verilated::traceEverOn(true);
-    tfp = new VerilatedVcdC;
+    tfp = new VERILATED_DUMP;
     top->trace(tfp, 99);
-    tfp->open("simx.vcd");
+  #ifndef TRACE_FILEPATH
+    tfp->open(DEF_TRACE_FILEPATH);
+  #else
+    tfp->open(TRACE_FILEPATH);
+  #endif
 #endif
 
     return cfu;
 }
+
diff --git a/docs/source/images/test-projects-workflow.png b/docs/source/images/test-projects-workflow.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -57,8 +57,11 @@ RISCV, Custom Function Units and `Tensorflow Lite for Microcontrollers`_.
 
 :doc:`step-by-step` will guide you through creating your first accelerator.
 
+:doc:`renode` can tell you more about simulating your project in `Renode`_.
+
 .. _`Tensorflow Lite for Microcontrollers`: https://www.tensorflow.org/lite/microcontrollers
 .. _nMigen: https://github.com/nmigen/nmigen
+.. _Renode: https://renode.io
 
 .. raw:: html
 
@@ -78,6 +81,7 @@ Site Index
    setup-guide
    crash-course/index
    step-by-step
+   renode
    vivado-install
    docs/index
    projects/*

diff --git a/docs/source/overview.rst b/docs/source/overview.rst
@@ -88,3 +88,15 @@ software includes:
 
 .. _`Tensorflow Lite for Microcontrollers`: https://www.tensorflow.org/lite/microcontrollers
 
+
+Testing and simulation
+----------------------
+
+We use Renode_, an open source simulation framework by Antmicro_, enabling you to run the software without having the hardware available.
+
+Renode simulates the whole SoC and is able to use co-simulation with verilated CFU models to test the end-to-end flow of your application.
+
+Consult the :doc:`renode` documentation for additional details.
+
+.. _Renode: https://renode.io
+.. _Antmicro: https://antmicro.com
diff --git a/docs/source/renode.rst b/docs/source/renode.rst
diff --git a/proj/proj.mk b/proj/proj.mk
@@ -169,7 +169,7 @@ else ifeq '$(PLATFORM)' 'common_soc'
 else ifeq '$(PLATFORM)' 'sim'
 	SOC_MK   := $(SIM_MK)
 else
-	$(error PLATFORM must be 'arty' or 'nexys_video' or 'qmtech_wukong' or 'sim')
+	$(error PLATFORM must be 'common_soc' or 'hps' or 'sim')
 endif
 
 TARGET_REPL := $(BUILD_DIR)/renode/$(TARGET)_generated.repl
@@ -178,24 +178,34 @@ ifneq '$(VERILATOR_TRACE_DEPTH)' ''
 	ENABLE_TRACE_ARG := --trace
 endif
 
+ifeq '$(ENABLE_TRACE_ARG)' '--trace'
+	VERILATOR_TRACE_PATH := $(BUILD_DIR)/simx.vcd
+else ifeq '$(ENABLE_TRACE_ARG)' '--trace-fst'
+	VERILATOR_TRACE_PATH := $(BUILD_DIR)/simx.fst
+endif
+
 BUILD_JOBS ?= 1
 
 .PHONY:	renode
 renode: renode-scripts
 	@echo Running interactively under renode
-	pushd $(PROJ_DIR)/build/renode/ && $(RENODE_DIR)/renode -e "s @$(TARGET).resc" && popd
+	pushd $(BUILD_DIR)/renode/ && $(RENODE_DIR)/renode -e "s @$(TARGET).resc" && popd
 
 .PHONY:	renode-headless
 renode-headless: renode-scripts
-	pushd $(PROJ_DIR)/build/renode/ && $(RENODE_DIR)/renode --console --disable-xwt --hide-log -e "s @$(TARGET).resc ; uart_connect sysbus.uart" && popd
+	pushd $(BUILD_DIR)/renode/ && $(RENODE_DIR)/renode --console --disable-xwt --hide-log -e "s @$(TARGET).resc ; uart_connect sysbus.uart" && popd
+
+.PHONY:	renode-test
+renode-test: renode-scripts
+	$(RENODE_DIR)/renode-test $(BUILD_DIR)/renode/$(TARGET).robot
 
 .PHONY: renode-scripts
 renode-scripts: $(SOFTWARE_ELF)
 	@mkdir -p $(BUILD_DIR)/renode
 ifneq '$(SW_ONLY)' '1'
 	pushd $(BUILD_DIR)/renode && cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_TRACE=$(ENABLE_TRACE_ARG) -DTRACE_DEPTH_VAL=$(VERILATOR_TRACE_DEPTH) \
 		-DINCLUDE_DIR="$(PROJ_DIR)" -DVTOP="$(CFU_VERILOG)" -DVIL_DIR="$(VIL_DIR)" $${VERILATOR_PATH:+"-DUSER_VERILATOR_DIR=$$VERILATOR_PATH"} \
-		"$(RVI_DIR)" && make libVtop && popd
+		-DTRACE_FILEPATH="$(VERILATOR_TRACE_PATH)" "$(RVI_DIR)" && make libVtop && popd
 	$(CFU_ROOT)/scripts/generate_renode_scripts.py $(SOC_BUILD_DIR)/csr.json $(TARGET) $(BUILD_DIR)/renode/ --repl $(TARGET_REPL)
 else
 	$(CFU_ROOT)/scripts/generate_renode_scripts.py $(SOC_BUILD_DIR)/csr.json $(TARGET) $(BUILD_DIR)/renode/ --repl $(TARGET_REPL) --sw-only
@@ -277,17 +287,25 @@ endif
 litex-software: $(CFU_VERILOG)
 	$(SOC_MK) litex-software
 
-RUN_TARGETS := load unit run unit-renode run-renode
-.PHONY: $(RUN_TARGETS) prog bitstream
+TTY_TARGETS := load unit run
+.PHONY: $(TTY_TARGETS) prog bitstream run-renode unit-renode
 
 ifneq 'sim' '$(PLATFORM)'
-# $(PLATFORM) == 'arty'
+# $(PLATFORM) == 'common_soc' or 'hps'
 prog: $(CFU_VERILOG)
 	$(SOC_MK) prog
 
 bitstream: $(CFU_VERILOG)
 	$(SOC_MK) bitstream
 
+run-renode: $(SOFTWARE_ELF) renode-scripts
+	@echo Running automated test in Renode
+	$(BUILD_DIR)/interact.expect r $(RUN_MENU_ITEMS) |& tee $(SOFTWARE_LOG)
+
+unit-renode: $(SOFTWARE_ELF) renode-scripts
+	@echo Running unit test in Renode simulation
+	$(BUILD_DIR)/interact.expect r $(TEST_MENU_ITEMS) |& tee $(UNITTEST_LOG)
+
 ifeq '1' '$(words $(TTY))'
 run: $(SOFTWARE_BIN)
 	@echo Running automated pdti8 test on board
@@ -297,14 +315,6 @@ unit: $(SOFTWARE_BIN)
 	@echo Running unit test on board
 	$(BUILD_DIR)/interact.expect $(SOFTWARE_BIN) $(TTY) $(UART_SPEED) $(TEST_MENU_ITEMS) |& tee $(UNITTEST_LOG)
 
-run-renode: $(SOFTWARE_ELF) renode-scripts
-	@echo Running automated test in Renode
-	$(BUILD_DIR)/interact.expect r $(RUN_MENU_ITEMS) |& tee $(SOFTWARE_LOG)
-
-unit-renode: $(SOFTWARE_ELF) renode-scripts
-	@echo Running unit test in Renode simulation
-	$(BUILD_DIR)/interact.expect r $(TEST_MENU_ITEMS) |& tee $(UNITTEST_LOG)
-
 ifeq 'hps' '$(PLATFORM)'
 load: $(SOFTWARE_BIN)
 	@echo Running interactively on HPS Board
@@ -329,7 +339,7 @@ connect:
 endif
 
 else
-$(RUN_TARGETS):
+$(TTY_TARGETS):
 	@echo Error: could not determine unique TTY
 	@echo TTY possibilities: $(TTY)
 	@echo Optionally, manually specify TTY= on the command line