diff --git a/.circleci/build-verilator.sh b/.circleci/build-verilator.sh index 2c0b6a13..acd038fb 100755 --- a/.circleci/build-verilator.sh +++ b/.circleci/build-verilator.sh @@ -23,7 +23,7 @@ if [ ! -d "$LOCAL_VERILATOR_DIR" ]; then run "mkdir -p $REMOTE_CHIPYARD_DIR" copy $LOCAL_CHIPYARD_DIR/ $SERVER:$REMOTE_CHIPYARD_DIR - run "make -C $REMOTE_CHIPYARD_DIR/sims/verisim VERILATOR_INSTALL_DIR=$REMOTE_VERILATOR_DIR verilator_install" + run "make -C $REMOTE_SIM_DIR VERILATOR_INSTALL_DIR=$REMOTE_VERILATOR_DIR verilator_install" # copy so that circleci can cache mkdir -p $LOCAL_CHIPYARD_DIR diff --git a/.circleci/check-commit.sh b/.circleci/check-commit.sh index 4ad48ed5..630bbd08 100755 --- a/.circleci/check-commit.sh +++ b/.circleci/check-commit.sh @@ -26,7 +26,7 @@ search () { done } -submodules=("boom" "firechip" "hwacha" "icenet" "rocket-chip" "sifive-blocks" "sifive-cache" "testchipip") +submodules=("boom" "hwacha" "icenet" "rocket-chip" "sifive-blocks" "sifive-cache" "testchipip") dir="generators" search diff --git a/.circleci/config.yml b/.circleci/config.yml index ab514d36..4630446d 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -78,14 +78,14 @@ jobs: - checkout - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Build Verilator command: | .circleci/build-verilator.sh no_output_timeout: 120m - save_cache: - key: verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + key: verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} paths: - "/home/riscvuser/verilator" prepare-example: @@ -108,7 +108,7 @@ jobs: - riscv-tools-installed-v1-{{ checksum "../riscv-tools.hash" }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Building the example subproject using Verilator command: .circleci/do-rtl-build.sh example @@ -137,7 +137,7 @@ jobs: - riscv-tools-installed-v1-{{ checksum "../riscv-tools.hash" }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Building the boomexample subproject using Verilator command: .circleci/do-rtl-build.sh boomexample @@ -166,7 +166,7 @@ jobs: - riscv-tools-installed-v1-{{ checksum "../riscv-tools.hash" }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Building the boomrocketexample subproject using Verilator command: .circleci/do-rtl-build.sh boomrocketexample @@ -195,7 +195,7 @@ jobs: - riscv-tools-installed-v1-{{ checksum "../riscv-tools.hash" }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Building the boom subproject using Verilator command: .circleci/do-rtl-build.sh boom @@ -224,7 +224,7 @@ jobs: - riscv-tools-installed-v1-{{ checksum "../riscv-tools.hash" }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Building the rocketchip subproject using Verilator command: .circleci/do-rtl-build.sh rocketchip @@ -282,7 +282,7 @@ jobs: - esp-tools-installed-v1-{{ checksum "../esp-tools.hash" }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Building the hwacha subproject using Verilator command: .circleci/do-rtl-build.sh hwacha @@ -311,7 +311,7 @@ jobs: - example-{{ .Branch }}-{{ .Revision }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Run example tests command: .circleci/run-tests.sh example @@ -335,7 +335,7 @@ jobs: - boomexample-{{ .Branch }}-{{ .Revision }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Run boomexample tests command: .circleci/run-tests.sh boomexample @@ -359,7 +359,7 @@ jobs: - boomrocketexample-{{ .Branch }}-{{ .Revision }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Run boomrocketexample tests command: .circleci/run-tests.sh boomrocketexample @@ -383,7 +383,7 @@ jobs: - boom-{{ .Branch }}-{{ .Revision }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Run boom tests command: .circleci/run-tests.sh boom @@ -407,7 +407,7 @@ jobs: - rocketchip-{{ .Branch }}-{{ .Revision }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Run rocketchip tests command: .circleci/run-tests.sh rocketchip @@ -431,7 +431,7 @@ jobs: - hwacha-{{ .Branch }}-{{ .Revision }} - restore_cache: keys: - - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }} + - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }} - run: name: Run hwacha tests command: .circleci/run-tests.sh hwacha diff --git a/.circleci/defaults.sh b/.circleci/defaults.sh index 5427852f..e777af65 100755 --- a/.circleci/defaults.sh +++ b/.circleci/defaults.sh @@ -23,7 +23,7 @@ REMOTE_RISCV_DIR=$REMOTE_WORK_DIR/riscv-tools-install REMOTE_ESP_DIR=$REMOTE_WORK_DIR/esp-tools-install REMOTE_CHIPYARD_DIR=$REMOTE_WORK_DIR/chipyard REMOTE_VERILATOR_DIR=$REMOTE_WORK_DIR/verilator -REMOTE_SIM_DIR=$REMOTE_CHIPYARD_DIR/sims/verisim +REMOTE_SIM_DIR=$REMOTE_CHIPYARD_DIR/sims/verilator # local variables (aka within the docker container) LOCAL_CHECKOUT_DIR=$HOME/project @@ -31,7 +31,7 @@ LOCAL_RISCV_DIR=$HOME/riscv-tools-install LOCAL_ESP_DIR=$HOME/esp-tools-install LOCAL_CHIPYARD_DIR=$LOCAL_CHECKOUT_DIR LOCAL_VERILATOR_DIR=$HOME/verilator -LOCAL_SIM_DIR=$LOCAL_CHIPYARD_DIR/sims/verisim +LOCAL_SIM_DIR=$LOCAL_CHIPYARD_DIR/sims/verilator # key value store to get the build strings declare -A mapping diff --git a/README.md b/README.md index e59f5af5..fd6e723f 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# Chipyard Framework [![CircleCI](https://circleci.com/gh/ucb-bar/project-template/tree/master.svg?style=svg)](https://circleci.com/gh/ucb-bar/chipyard/tree/master) +# Chipyard Framework [![CircleCI](https://circleci.com/gh/ucb-bar/chipyard/tree/master.svg?style=svg)](https://circleci.com/gh/ucb-bar/chipyard/tree/master) ## Using Chipyard -To get started using Chipyard, see the documentation on the Chipyard documentation site: https://bar-project-template.readthedocs.io/en/latest/ +To get started using Chipyard, see the documentation on the Chipyard documentation site: https://chipyard.readthedocs.io/en/latest/ ## What is Chipyard @@ -14,7 +14,7 @@ Chipyard is actively developed in the [Berkeley Architecture Research Group][ucb ## Resources * Chipyard Website: ...TBD at a later date... -* Chipyard Documentation: https://bar-project-template.readthedocs.io/ +* Chipyard Documentation: https://chipyard.readthedocs.io/ [hwacha]:http://hwacha.org [hammer]:https://github.com/ucb-bar/hammer diff --git a/common.mk b/common.mk index 29c2713b..cc2469a7 100644 --- a/common.mk +++ b/common.mk @@ -80,8 +80,9 @@ $(sim_files): $(sim_top_blackboxes) $(sim_harness_blackboxes) $(sim_dotf) verilog: $(sim_vsrcs) ######################################################################################### -# helper rules to run simulator +# helper rules to run simulations ######################################################################################### +.PHONY: run-binary run-fast run-binary: $(sim) (set -o pipefail && $(sim) $(PERMISSIVE_ON) +max-cycles=$(timeout_cycles) $(SIM_FLAGS) $(VERBOSE_FLAGS) $(PERMISSIVE_OFF) $(BINARY) 3>&1 1>&2 2>&3 | spike-dasm > $(sim_out_name).out) @@ -97,6 +98,8 @@ run-binary-fast: $(sim) run-binary-debug: $(sim_debug) (set -o pipefail && $(sim_debug) $(PERMISSIVE_ON) +max-cycles=$(timeout_cycles) $(SIM_FLAGS) $(VERBOSE_FLAG) $(WAVEFORM_FLAG) $(PERMISSIVE_OFF) $(BINARY) 3>&1 1>&2 2>&3 | spike-dasm > $(sim_out_name).out) +run-fast: run-asm-tests-fast run-bmark-tests-fast + ######################################################################################### # run assembly/benchmarks rules ######################################################################################### diff --git a/docs/Simulation/FPGA-Accelerated-Simulators.rst b/docs/Simulation/FPGA-Accelerated-Simulators.rst new file mode 100644 index 00000000..6dab6378 --- /dev/null +++ b/docs/Simulation/FPGA-Accelerated-Simulators.rst @@ -0,0 +1,57 @@ +FPGA-Accelerated Simulators +============================== + +FireSim +----------------------- + +`FireSim `__ is an open-source cycle-accurate FPGA-accelerated full-system hardware simulation platform that runs on cloud FPGAs (Amazon EC2 F1). +FireSim allows RTL-level simulation at orders-of-magnitude faster speeds than software RTL simulators. +FireSim also provides additional device models to allow full-system simulation, including memory models and network models. + +FireSim currently supports running only on Amazon EC2 F1 FPGA-enabled virtual instances. +In order to simulate your Chipyard design using FireSim, if you have not +already, follow the initial EC2 setup instructions as detailed in the `FireSim +documentation `__. +Then clone Chipyard onto your FireSim manager +instance, and setup your Chipyard repository as you would normally. + +Next, initalize FireSim as library in Chipyard by running: + +.. code-block:: shell + + # At the root of your chipyard repo + ./scripts/firesim-setup.sh --fast + +``firesim-setup.sh`` initializes additional submodules and then invokes +firesim's ``build-setup.sh`` script adding ``--library`` to properly +initialize FireSim as a library submodule in chipyard. You may run +``./sims/firesim/build-setup.sh --help`` to see more options. + +Finally, source the following environment at the root of the firesim directory: + +.. code-block:: shell + + cd sims/firesim + # (Recommended) The default manager environment (includes env.sh) + source sourceme-f1-manager.sh + +`Every time you want to use FireSim with a fresh shell, you must source this sourceme.sh` + +At this point you're ready to use FireSim with Chipyard. If you're not already +familiar with FireSim, please return to the `FireSim Docs +`__, +and proceed with the rest of the tutorial. + +Current Limitations: +++++++++++++++++++++ + +FireSim integration in Chipyard is still a work in progress. Presently, you +cannot build a FireSim simulator from any generator project in Chipyard except ``firechip``, +which properly invokes MIDAS on the target RTL. + +In the interim, workaround this limitation by importing Config and Module +classes from other generator projects into FireChip. You should then be able to +refer to those classes or an alias of them in your ``DESIGN`` or ``TARGET_CONFIG`` +variables. Note that if your target machine has I/O not provided in the default +FireChip targets (see ``generators/firechip/src/main/scala/Targets.scala``) you may need +to write a custom endpoint. diff --git a/docs/Simulation/FPGA-Based-Simulators.rst b/docs/Simulation/FPGA-Based-Simulators.rst deleted file mode 100644 index 1180b470..00000000 --- a/docs/Simulation/FPGA-Based-Simulators.rst +++ /dev/null @@ -1,17 +0,0 @@ -FPGA-Based Simulators -============================== - -FireSim ------------------------ - -`FireSim `__ is an open-source cycle-accurate FPGA-accelerated full-system hardware simulation platform that runs on cloud FPGAs (Amazon EC2 F1). -FireSim allows RTL-level simulation at orders-of-magnitude faster speeds than software RTL simulators. -FireSim also provides additional device models to allow full-system simulation, including memory models and network models. - -FireSim currently supports running only on Amazon EC2 F1 FPGA-enabled virtual instances on the public cloud. -In order to simulate your Chipyard design using FireSim, you should follow the following steps: - -Follow the initial EC2 setup instructions as detailed in the `FireSim documentation `__. -Then clone your full Chipyard repository onto your Amazon EC2 FireSim manager instance. - -Enter the ``sims/FireSim`` directory, and follow the FireSim instructions for `running a simulation `__. diff --git a/docs/Simulation/Open-Source-Simulators.rst b/docs/Simulation/Open-Source-Simulators.rst deleted file mode 100644 index bc8a0dcc..00000000 --- a/docs/Simulation/Open-Source-Simulators.rst +++ /dev/null @@ -1,35 +0,0 @@ -Open Source Software RTL Simulators -============================== - -Verilator ------------------------ - -`Verilator `__ is an open-source LGPL-Licensed simulator maintained by `Veripool `__. -The Chipyard framework can download, build, and execute simulations using Verilator. - -To run a simulation using Verilator, perform the following steps: - -To compile the example design, run ``make`` in the ``sims/verisim`` directory. -This will elaborate the ``DefaultRocketConfig`` in the example project. - -An executable called ``simulator-example-DefaultRocketConfig`` will be produced. -This executable is a simulator that has been compiled based on the design that was built. -You can then use this executable to run any compatible RV64 code. -For instance, to run one of the riscv-tools assembly tests. - -.. code-block:: shell - - ./simulator-example-DefaultRocketConfig $RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple - -If you later create your own project, you can use environment variables to build an alternate configuration. - -.. code-block:: shell - - make SUB_PROJECT=yourproject - ./simulator-- ... - -If you would like to extract waveforms from the simulation, run the command ``make debug`` instead of just ``make``. -This will generate a vcd file (vcd is a standard waveform representation file format) that can be loaded to any common waveform viewer. -An open-source vcd-capable waveform viewer is `GTKWave `__. - -Please refer to :ref:`Running A Simulation` for a step by step tutorial on how to get a simulator up and running. diff --git a/docs/Simulation/Commercial-Simulators.rst b/docs/Simulation/Software-RTL-Simulators.rst similarity index 50% rename from docs/Simulation/Commercial-Simulators.rst rename to docs/Simulation/Software-RTL-Simulators.rst index 0e971d51..9df94d52 100644 --- a/docs/Simulation/Commercial-Simulators.rst +++ b/docs/Simulation/Software-RTL-Simulators.rst @@ -1,9 +1,43 @@ -Commercial Software RTL Simulators -============================== +Software RTL Simulators +=================================== -VCS +Verilator (Open-Source) ----------------------- +`Verilator `__ is an open-source LGPL-Licensed simulator maintained by `Veripool `__. +The Chipyard framework can download, build, and execute simulations using Verilator. + +To run a simulation using Verilator, perform the following steps: + +To compile the example design, run ``make`` in the ``sims/verisim`` directory. +This will elaborate the ``DefaultRocketConfig`` in the example project. + +An executable called ``simulator-example-DefaultRocketConfig`` will be produced. +This executable is a simulator that has been compiled based on the design that was built. +You can then use this executable to run any compatible RV64 code. +For instance, to run one of the riscv-tools assembly tests. + +.. code-block:: shell + + ./simulator-example-DefaultRocketConfig $RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple + +If you later create your own project, you can use environment variables to build an alternate configuration. + +.. code-block:: shell + + make SUB_PROJECT=yourproject + ./simulator-- ... + +If you would like to extract waveforms from the simulation, run the command ``make debug`` instead of just ``make``. +This will generate a vcd file (vcd is a standard waveform representation file format) that can be loaded to any common waveform viewer. +An open-source vcd-capable waveform viewer is `GTKWave `__. + +Please refer to :ref:`Running A Simulation` for a step by step tutorial on how to get a simulator up and running. +Commercial Software RTL Simulators + +Synopsys VCS (License Required) +-------------------------------- + `VCS `__ is a commercial RTL simulator developed by Synopsys. It requires commercial licenses. The Chipyard framework can compile and execute simulations using VCS. diff --git a/docs/Simulation/index.rst b/docs/Simulation/index.rst index 339960bd..50dbb57e 100644 --- a/docs/Simulation/index.rst +++ b/docs/Simulation/index.rst @@ -1,15 +1,20 @@ Simulators ======================= -Chipyard provides support and integration for multiple simulation flows, for various user levels and requirements. -In the majority of cases during a digital design development process, a simple software RTL simulation will do. -When more advanced full-system evaluation is required, with long running workloads, FPGA-accelerated simulation will then become a preferable solution. -The following pages provide detailed information about the simulation possibilities within the Chipyard framework. +Chipyard supports two classes of simulation: + +#. Software RTL simulation using commercial or open-source (Verilator) RTL simulators +#. FPGA-accelerated full-system simulation using FireSim + +Software RTL simulators of Chipyard designs run at O(1 KHz), but compile +quickly and provide full waveforms. Conversly, FPGA-accelerated simulators run +at O(100 MHz), making them appropriate for booting an operating system and +running a complete workload, but have multi-hour compile times and poorer debug +visability. .. toctree:: :maxdepth: 2 :caption: Simulators: - Open-Source-Simulators - Commercial-Simulators - FPGA-Based-Simulators + Software-RTL-Simulators + FPGA-Accelerated-Simulators diff --git a/docs/index.rst b/docs/index.rst index 019a6991..b2fa001a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,7 @@ contain the root `toctree` directive. Welcome to Chipyard's documentation! -================================= +==================================== Chipyard is a a framework for designing and evaluating full-system hardware using agile teams. It is composed of a collection of tools and libraries designed to provide an intergration between open-source and commercial tools for the development of systems-on-chip. diff --git a/sims/vsim/.gitignore b/sims/vcs/.gitignore similarity index 100% rename from sims/vsim/.gitignore rename to sims/vcs/.gitignore diff --git a/sims/vsim/Makefile b/sims/vcs/Makefile similarity index 99% rename from sims/vsim/Makefile rename to sims/vcs/Makefile index c96155ba..8f0ebbe0 100644 --- a/sims/vsim/Makefile +++ b/sims/vcs/Makefile @@ -56,6 +56,7 @@ VCS_NONCC_OPTS = \ -error=PCWM-L \ -timescale=1ns/10ps \ -quiet \ + -q \ +rad \ +v2k \ +vcs+lic+wait \ diff --git a/sims/verisim/.gitignore b/sims/verilator/.gitignore similarity index 100% rename from sims/verisim/.gitignore rename to sims/verilator/.gitignore diff --git a/sims/verisim/Makefile b/sims/verilator/Makefile similarity index 100% rename from sims/verisim/Makefile rename to sims/verilator/Makefile diff --git a/sims/verisim/verilator.mk b/sims/verilator/verilator.mk similarity index 100% rename from sims/verisim/verilator.mk rename to sims/verilator/verilator.mk