Merge pull request #142 from ucb-bar/firesim-docs

Update FireSim Instructions

docs/Simulation/FPGA-Accelerated-Simulators.rst

@@ -0,0 +1,57 @@
+FPGA-Accelerated Simulators
+==============================
+
+FireSim
+-----------------------
+
+`FireSim <https://fires.im/>`__ 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  <http://docs.fires.im/en/latest/Initial-Setup/index.html>`__.
+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
+<https://docs.fires.im/en/latest/Initial-Setup/Setting-up-your-Manager-Instance.html#completing-setup-using-the-manager>`__,
+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.

docs/Simulation/FPGA-Based-Simulators.rst

@@ -1,17 +0,0 @@
-FPGA-Based Simulators
-==============================
-
-FireSim
------------------------
-
-`FireSim <https://fires.im/>`__ 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  <http://docs.fires.im/en/latest/Initial-Setup/index.html>`__.
-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 <http://docs.fires.im/en/latest/Running-Simulations-Tutorial/index.html>`__.

docs/Simulation/Open-Source-Simulators.rst

@@ -1,35 +0,0 @@
-Open Source Software RTL Simulators
-==============================
-
-Verilator
------------------------
-
-`Verilator <https://www.veripool.org/wiki/verilator>`__ is an open-source LGPL-Licensed simulator maintained by `Veripool <https://www.veripool.org/>`__.
-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-<yourproject>-<yourconfig> ...
-
-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 <http://gtkwave.sourceforge.net/>`__.
-
-Please refer to :ref:`Running A Simulation` for a step by step tutorial on how to get a simulator up and running.

docs/Simulation/Software-RTL-Simulators.rst

@@ -1,9 +1,43 @@
-Commercial Software RTL Simulators
+Software RTL Simulators
-==============================
+===================================
 
-VCS
+Verilator (Open-Source)
 -----------------------
 
+`Verilator <https://www.veripool.org/wiki/verilator>`__ is an open-source LGPL-Licensed simulator maintained by `Veripool <https://www.veripool.org/>`__.
+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-<yourproject>-<yourconfig> ...
+
+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 <http://gtkwave.sourceforge.net/>`__.
+
+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 <https://www.synopsys.com/verification/simulation/vcs.html>`__ is a commercial RTL simulator developed by Synopsys.
 It requires commercial licenses.
 The Chipyard framework can compile and execute simulations using VCS.

docs/Simulation/index.rst

@@ -1,15 +1,20 @@
 Simulators
 =======================
 
-Chipyard provides support and integration for multiple simulation flows, for various user levels and requirements.
+Chipyard supports two classes of simulation:
-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.
+#. Software RTL simulation using commercial or open-source (Verilator) RTL simulators 
-The following pages provide detailed information about the simulation possibilities within the Chipyard framework.
+#. 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
+   Software-RTL-Simulators
-   Commercial-Simulators
+   FPGA-Accelerated-Simulators
-   FPGA-Based-Simulators

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.