Make help target and VCS/Verilator Cleanup

.gitignore

@@ -6,6 +6,7 @@ target
 *.stamp
 *.vcd
 *.swp
+*.swo
 *.log
 *#
 *~

common.mk

@@ -3,22 +3,46 @@
 #########################################################################################
 SHELL=/bin/bash
 
-
 ifndef RISCV
 $(error RISCV is unset. You must set RISCV yourself, or through the Chipyard auto-generated env file)
 else
 $(info Running with RISCV=$(RISCV))
 endif
 
+#########################################################################################
+# specify user-interface variables
+#########################################################################################
+HELP_COMPILATION_VARIABLES += \
+"   EXTRA_GENERATOR_REQS   = requirements needed for the main generator" \
+"   EXTRA_SIM_CFLAGS       = CFLAGS for building simulators" \
+"   EXTRA_SIM_CXXFLAGS     = CXXFLAGS for building simulators" \
+"   EXTRA_SIM_LDFLAGS      = LDFLAGS for building simulators" \
+"   EXTRA_SIM_SOURCES      = simulation sources needed for simulator" \
+"   EXTRA_SIM_REQS         = requirements to build the simulator"
+
+EXTRA_GENERATOR_REQS ?=
+EXTRA_SIM_CXXFLAGS   ?=
+EXTRA_SIM_CFLAGS     ?=
+EXTRA_SIM_LDFLAGS    ?=
+EXTRA_SIM_SOURCES    ?=
+EXTRA_SIM_REQS       ?=
+
+#----------------------------------------------------------------------------
+HELP_SIMULATION_VARIABLES += \
+"   EXTRA_SIM_FLAGS        = runtime simulation flags (passed within +permissive)"
+
+EXTRA_SIM_FLAGS ?=
+
+#----------------------------------------------------------------------------
+HELP_COMMANDS += \
+"   run-binary             = run [./$(shell basename $(sim))] and log instructions to file" \
+"   run-binary-fast        = run [./$(shell basename $(sim))] and don't log instructions" \
+"   run-binary-debug       = run [./$(shell basename $(sim_debug))] and log instructions and waveform to files" \
+"   verilog                = generate intermediate verilog files from chisel elaboration and firrtl passes"
 
 #########################################################################################
-# extra make variables/rules from subprojects
-#
-# EXTRA_GENERATOR_REQS - requirements needed for the main generator
-# EXTRA_SIM_FLAGS - runtime simulation flags
-# EXTRA_SIM_CC_FLAGS - cc flags for simulators
-# EXTRA_SIM_SOURCES - simulation sources needed for simulator
-# EXTRA_SIM_REQS - requirements to build the simulator
+# include additional subproject make fragments
+# see HELP_COMPILATION_VARIABLES
 #########################################################################################
 include $(base_dir)/generators/ariane/ariane.mk
 include $(base_dir)/generators/tracegen/tracegen.mk
@@ -55,7 +79,6 @@ $(FIRRTL_TEST_JAR): $(call lookup_srcs,$(CHIPYARD_FIRRTL_DIR),scala)
 	cp -p $(CHIPYARD_FIRRTL_DIR)/utils/bin/firrtl-test.jar $@
 	touch $@
 
-
 #########################################################################################
 # Bloop Project Definitions
 #########################################################################################
@@ -139,19 +162,19 @@ verilog: $(sim_vsrcs)
 #########################################################################################
 # helper rules to run simulations
 #########################################################################################
-.PHONY: run-binary run-binary-fast run-binary-debug run-fast
+.PHONY: run-binary run-binary-fast
+.PHONY: run-binary-debug
+.PHONY: run-fast
+
+# run normal binary with hardware-logged insn dissassembly
 run-binary: $(output_dir) $(sim)
 	(set -o pipefail && $(sim) $(PERMISSIVE_ON) $(SIM_FLAGS) $(EXTRA_SIM_FLAGS) $(SEED_FLAG) $(VERBOSE_FLAGS) $(PERMISSIVE_OFF) $(BINARY) </dev/null 2> >(spike-dasm > $(sim_out_name).out) | tee $(sim_out_name).log)
 
-#########################################################################################
-# helper rules to run simulator as fast as possible
-#########################################################################################
+# run simulator as fast as possible (no insn disassembly)
 run-binary-fast: $(output_dir) $(sim)
 	(set -o pipefail && $(sim) $(PERMISSIVE_ON) $(SIM_FLAGS) $(EXTRA_SIM_FLAGS) $(SEED_FLAG) $(PERMISSIVE_OFF) $(BINARY) </dev/null | tee $(sim_out_name).log)
 
-#########################################################################################
-# helper rules to run simulator with as much debug info as possible
-#########################################################################################
+# run simulator with as much debug info as possible
 run-binary-debug: $(output_dir) $(sim_debug)
 	(set -o pipefail && $(sim_debug) $(PERMISSIVE_ON) $(SIM_FLAGS) $(EXTRA_SIM_FLAGS) $(SEED_FLAG) $(VERBOSE_FLAGS) $(WAVEFORM_FLAG) $(PERMISSIVE_OFF) $(BINARY) </dev/null 2> >(spike-dasm > $(sim_out_name).out) | tee $(sim_out_name).log)
 

docs/Simulation/Software-RTL-Simulation.rst

@@ -40,8 +40,7 @@ For a proprietry VCS simulation, enter the ``sims/vcs`` directory
     # Enter VCS directory
     cd sims/vcs
 
-
-.. _sim-default:
+.. _sw-sim-help:
 
 Simulating The Default Example
 -------------------------------
@@ -62,12 +61,6 @@ For instance, to run one of the riscv-tools assembly tests.
 
 .. Note:: In a VCS simulator, the simulator name will be ``simv-chipyard-RocketConfig`` instead of ``simulator-chipyard-RocketConfig``.
 
-The makefiles have a ``run-binary`` rule that simplifies running the simulation executable. It adds many of the common command line options for you and redirects the output to a file.
-
-.. code-block:: shell
-
-    make run-binary BINARY=$RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple
-
 Alternatively, we can run a pre-packaged suite of RISC-V assembly or benchmark tests, by adding the make target ``run-asm-tests`` or ``run-bmark-tests``.
 For example:
 
@@ -82,6 +75,22 @@ For example:
 
 .. _sw-sim-custom:
 
+Makefile Variables and Commands
+-------------------------------
+You can get a list of useful Makefile variables and commands available from the Verilator or VCS directories. simply run ``make help``:
+
+.. code-block:: shell
+
+    # Enter Verilator directory
+    cd sims/verilator
+    make help
+
+    # Enter VCS directory
+    cd sims/vcs
+    make help
+
+.. _sim-default:
+
 Simulating A Custom Project
 -------------------------------
 
@@ -132,29 +141,6 @@ All ``make`` targets that can be applied to the default example, can also be app
 Finally, in the ``generated-src/<...>-<package>-<config>/`` directory resides all of the collateral and Verilog source files for the build/simulation.
 Specifically, the SoC top-level (``TOP``) Verilog file is denoted with ``*.top.v`` while the ``TestHarness`` file is denoted with ``*.harness.v``.
 
-Fast Memory Loading
--------------------
-
-The simulator loads the program binary over a simulated serial line. This can be quite slow if there is a lot of static data, so the simulator also allows data to be loaded from a file directly into the DRAM model.
-
-.. code-block:: shell
-
-    make run-binary BINARY=test.riscv LOADMEM=testdata.hex LOADMEM_ADDR=81000000
-
-The ``.hex`` file should be a text file with a hexadecimal number on each line.
-
-.. code-block:: text
-
-    deadbeef
-    0123
-
-Each line uses little-endian order, so this file would produce the bytes "ef be ad de 01 23". ``LOADMEM_ADDR`` specifies which address in memory (in hexadecimal) to write the first byte to. The default is 0x81000000.
-
-A special target that facilitates automatically generating a hex file for an entire elf RISC-V exectuable and then running the simulator with the appropriate flags is also available.
-
-.. code-block:: shell
-
-    make run-binary-hex BINARY=test.riscv
 
 Generating Waveforms
 -----------------------
@@ -166,4 +152,3 @@ An open-source vcd-capable waveform viewer is `GTKWave <http://gtkwave.sourcefor
 
 For a VCS simulation, this will generate a vpd file (this is a proprietary waveform representation format used by Synopsys) that can be loaded to vpd-supported waveform viewers.
 If you have Synopsys licenses, we recommend using the DVE waveform viewer.
-

sims/vcs/Makefile

@@ -25,7 +25,10 @@ sim_prefix = simv
 sim = $(sim_dir)/$(sim_prefix)-$(MODEL_PACKAGE)-$(CONFIG)
 sim_debug = $(sim_dir)/$(sim_prefix)-$(MODEL_PACKAGE)-$(CONFIG)-debug
 
-include $(base_dir)/vcs.mk
+PERMISSIVE_ON=+permissive
+PERMISSIVE_OFF=+permissive-off
+
+WAVEFORM_FLAG=+vcdplusfile=$(sim_out_name).vpd
 
 .PHONY: default debug
 default: $(sim)
@@ -36,22 +39,97 @@ debug: $(sim_debug)
 #########################################################################################
 include $(base_dir)/common.mk
 
+#########################################################################################
+# verilator-specific user-interface variables and commands
+#########################################################################################
+HELP_COMPILATION_VARIABLES +=
+HELP_COMMANDS += \
+"   default                = compiles non-debug simulator [./$(shell basename $(sim))]" \
+"   debug                  = compiles debug simulator [./$(shell basename $(sim_debug))]" \
+"   clean                  = remove all debug/non-debug simulators and intermediate files" \
+"   clean-sim              = removes non-debug simulator and verilator-generated files" \
+"   clean-sim-debug        = removes debug simulator and verilator-generated files"
+
 #########################################################################################
 # vcs binary and arguments
 #########################################################################################
 VCS = vcs -full64
 
-VCS_OPTS = -notice -line $(VCS_CC_OPTS) $(VCS_NONCC_OPTS) $(VCS_DEFINE_OPTS) $(EXTRA_SIM_SOURCES)
+PREPROC_DEFINES = \
+	+define+VCS \
+	+define+CLOCK_PERIOD=1.0 \
+	+define+PRINTF_COND=$(TB).printf_cond \
+	+define+STOP_COND=!$(TB).reset \
+	+define+RANDOMIZE_MEM_INIT \
+	+define+RANDOMIZE_REG_INIT \
+	+define+RANDOMIZE_GARBAGE_ASSIGN \
+	+define+RANDOMIZE_INVALID_ASSIGN
+
+VCS_NONCC_OPTS = \
+	-notice \
+	-line \
+	+lint=all,noVCDE,noONGS,noUI \
+	-timescale=1ns/1ps \
+	-quiet \
+	-q \
+	+rad \
+	+vcs+lic+wait \
+	+vc+list \
+	-error=noZMMCM \
+	-error=PCWM-L \
+	-sverilog +systemverilogext+.sv+.svi+.svh+.svt -assert svaext +libext+.sv \
+	+v2k +verilog2001ext+.v95+.vt+.vp +libext+.v \
+	+incdir+$(build_dir) \
+	$(PREPROC_DEFINES) \
+	-f $(sim_common_files) \
+	$(sim_vsrcs)
+
+#----------------------------------------------------------------------------------------
+# gcc configuration/optimization
+#----------------------------------------------------------------------------------------
+# -flto slows down compilation on small-memory and breaks on firesim-manager
+CMODE := -O3 -fbranch-probabilities -march=native
+
+VCS_CXXFLAGS = \
+	$(CXXFLAGS) \
+	$(CMODE) \
+	-I$(VCS_HOME)/include \
+	-I$(RISCV)/include \
+	-I$(dramsim_dir) \
+	-std=c++11 \
+	$(EXTRA_SIM_CXXFLAGS)
+
+VCS_LDFLAGS =	\
+	$(LDFLAGS) \
+	$(CMODE) \
+	-L$(RISCV)/lib \
+	-Wl,-rpath,$(RISCV)/lib \
+	-L$(sim_dir) \
+	-L$(dramsim_dir) \
+	-lfesvr \
+	-ldramsim \
+	$(EXTRA_SIM_LDFLAGS)
+
+VCS_CC_OPTS = \
+	-CFLAGS "$(VCS_CXXFLAGS)" \
+	-LDFLAGS "$(VCS_LDFLAGS)"
+
+#----------------------------------------------------------------------------------------
+# full vcs+gcc opts
+#----------------------------------------------------------------------------------------
+VCS_OPTS = $(VCS_CC_OPTS) $(VCS_NONCC_OPTS)
 
 #########################################################################################
 # vcs simulator rules
 #########################################################################################
 $(sim): $(sim_vsrcs) $(sim_common_files) $(dramsim_lib) $(EXTRA_SIM_REQS)
-	rm -rf csrc && $(VCS) $(VCS_OPTS) -o $@
+	rm -rf csrc && $(VCS) $(VCS_OPTS) $(EXTRA_SIM_SOURCES) -o $@ \
+	-debug_pp
 
 $(sim_debug): $(sim_vsrcs) $(sim_common_files) $(dramsim_lib) $(EXTRA_SIM_REQS)
-	rm -rf csrc && $(VCS) $(VCS_OPTS) -o $@ \
-	+define+DEBUG
+	rm -rf csrc && $(VCS) $(VCS_OPTS) $(EXTRA_SIM_SOURCES) -o $@ \
+	+define+DEBUG \
+	-debug_pp
 
 #########################################################################################
 # create a vcs vpd rule
@@ -60,9 +138,26 @@ $(sim_debug): $(sim_vsrcs) $(sim_common_files) $(dramsim_lib) $(EXTRA_SIM_REQS)
 $(output_dir)/%.vpd: $(output_dir)/% $(sim_debug)
 	(set -o pipefail && $(sim_debug) $(PERMISSIVE_ON) $(SIM_FLAGS) $(EXTRA_SIM_FLAGS) $(VERBOSE_FLAGS) +vcdplusfile=$@ $(PERMISSIVE_OFF) $< </dev/null 2> >(spike-dasm > $<.out) | tee $<.log)
 
+$(output_dir)/none.vpd: $(sim_debug)
+	mkdir -p $(output_dir)
+	(set -o pipefail && $(sim_debug) $(PERMISSIVE_ON) $(SIM_FLAGS) $(EXTRA_SIM_FLAGS) $(VERBOSE_FLAGS) +vcdplusfile=$@ $(PERMISSIVE_OFF) none </dev/null 2> >(spike-dasm > $(output_dir)/none.out) | tee $(output_dir)/none.log)
+
 #########################################################################################
-# general cleanup rule
+# general cleanup rules
 #########################################################################################
-.PHONY: clean
+.PHONY: clean clean-sim clean-sim-debug
 clean:
-	rm -rf $(gen_dir) csrc $(sim_prefix)-* ucli.key vc_hdrs.h
+	rm -rf $(gen_dir) $(sim_prefix)-*
+
+clean-sim:
+	rm -rf csrc/ $(sim) ucli.key vc_hdrs.h
+
+clean-sim-debug:
+	rm -rf csrc/ $(sim_debug) ucli.key vc_hdrs.h
+
+#########################################################################################
+# print help text
+#########################################################################################
+.PHONY: help
+help:
+	@for line in $(HELP_LINES); do echo "$$line"; done