wu-arch/chipyard
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

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

Browse Source 
Update FireSim Instructions
This commit is contained in:
David Biancolin
2019-07-16 12:53:27 -07:00
committed by GitHub
parent 26a67fdbad 870c7d53d3
commit 1520e239f1
6 changed files with 107 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
docs/Simulation/FPGA-Accelerated-Simulators.rst Normal file
View File

@@ -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.

17
docs/Simulation/FPGA-Based-Simulators.rst
View File

@@ -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>`__.

35
docs/Simulation/Open-Source-Simulators.rst
View File

@@ -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.

40
docs/Simulation/Commercial-Simulators.rst → docs/Simulation/Software-RTL-Simulators.rst
View File

@@ -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.

19
docs/Simulation/index.rst
View File

@@ -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

2
docs/index.rst
View File

@@ -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.