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.