Initial outline of FPGA prototyping docs

docs/Chipyard-Basics/Chipyard-Components.rst

@@ -106,12 +106,12 @@ Software
 Sims
 -------------------------------------------
 
-**verilator (Verilator wrapper)**
+**Verilator**
   Verilator is an open source Verilog simulator.
   The ``verilator`` directory provides wrappers which construct Verilator-based simulators from relevant generated RTL, allowing for execution of test RISC-V programs on the simulator (including vcd waveform files).
   See :ref:`Verilator (Open-Source)` for more information.
 
-**vcs (VCS wrapper)**
+**VCS**
   VCS is a proprietary Verilog simulator.
   Assuming the user has valid VCS licenses and installations, the ``vcs`` directory provides wrappers which construct VCS-based simulators from relevant generated RTL, allowing for execution of test RISC-V programs on the simulator (including vcd/vpd waveform files).
   See :ref:`Synopsys VCS (License Required)` for more information.
@@ -124,6 +124,13 @@ Sims
   In order to use FireSim, the repository must be cloned and executed on AWS instances.
   See :ref:`FireSim` for more information.
 
+**FPGA Prototyping**
+  FPGA prototyping is supported in Chipyard using SiFive's ``fpga-shells``.
+  Some examples of FPGA's supported are Arty and VCU118.
+  For more accurate and deterministic simulation results, please consider using the :ref:`FireSim` platform.
+  See :ref:`FPGA Prototyping` for more information.
+
+
 VLSI
 -------------------------------------------
 

docs/Simulation/FPGA-Prototyping.rst

@@ -0,0 +1,87 @@
+FPGA Prototyping
+==============================
+
+FPGA Prototyping
+-----------------------
+
+Chipyard supports FPGA prototyping for local FPGAs supported under ``fpga-shells`` <LINK>.
+This include popular FPGAs such as the Xilinx VCU118 and the Xilinx Arty board.
+FPGA prototyping allows RTL-level simulation at orders-of-magnitude faster speeds than software RTL simulators at the cost of slower compile times.
+
+Setup
+-----
+
+All FPGA related collateral is located in the ``fpga`` top-level Chipyard folder.
+To initialize the ``fpga-shells`` repository, run the included submodule script:
+
+.. code-block:: shell
+
+    # in the chipyard top level folder
+    ./scripts/init-fpga.sh
+
+Making a Bitstream
+------------------
+
+Making a bitstream for any FPGA is similar to building RTL for a software RTL simulation.
+Similar to the :ref:`Simulating A Custom Project` section in the :ref:`Software RTL Simulation` section you can run the following command in the ``fpga`` directory.
+
+.. code-block:: shell
+
+    make SBT_PROJECT=... MODEL=... VLOG_MODEL=... MODEL_PACKAGE=... CONFIG=... CONFIG_PACKAGE=... GENERATOR_PACKAGE=... TB=... TOP=... bit
+
+    # or
+
+    make SUB_PROJECT=<sub_project> bit
+
+By default a couple of ``SUB_PROJECT``'s are already defined for use, including ``vcu118`` and ``arty``.
+These default ``SUB_PROJECT``'s setup the necessary test harnesses, packages, and more.
+In most cases, you will just need to run a command with a ``SUB_PROJECT`` and an overridden ``CONFIG`` to point to.
+For example, building the BOOM configuration on the VCU118:
+
+.. code-block:: shell
+
+    make SUB_PROJECT=vcu118 CONFIG=BoomVCU118Config
+
+Running a Design on Arty
+------------------------
+
+Running a Design on VCU118
+--------------------------
+
+Basic Design
+~~~~~~~~~~~~
+
+The default VCU118 design is setup to run RISC-V Linux from an SDCard while piping the terminal over UART.
+To change the design, you can create your own configuration and add the ``AbstractVCU118Config`` located in ``fpga/src/main/scala/vcu118/Configs.scala``.
+Adding this config. fragment will enable and connect the UART, SPI SDCard, and DDR backing memory.
+Notice that the majority of config. fragments in ``AbstractVCU118Config`` are shared with a normal Chipyard config.
+
+.. literalinclude:: ../../fpga/src/main/scala/vcu118/Configs.scala
+    :language: scala
+    :start-after: DOC include start: AbstractVCU118 and Rocket
+    :end-before: DOC include end: AbstractVCU118 and Rocket
+
+fpga-shells / Overlays / HarnessBinders
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To make meaningful VCU118 changes (adding new IOs, connecting to different VCU118 ports, etc), the ``VCU118TestHarness`` must change.
+The ``VCU118TestHarness`` uses ``fpga-shells`` to add ``Overlays`` that connect to the VCU118 external IOs.
+``fpga/src/main/scala/vcu118/TestHarness.scala`` shows an example of using these ``Overlays``.
+First ``Overlays`` must be "placed" which adds them to the design.
+For example, the following shows a UART overlay being placed into the design.
+
+.. literalinclude:: ../../fpga/src/main/scala/vcu118/TestHarness.scala
+    :language: scala
+    :start-after: DOC include start: UartOverlay
+    :end-before: DOC include end: UartOverlay
+
+Here the ``UARTOverlayKey`` is referenced and used to "place" the necessary connections (and collateral) to connect to the UART.
+The ``UARTDesignInput`` is used to pass in the UART signals used to connect to the external UART IO.
+This is similar to all the other ``Overlays``.
+They must be "placed" and given a set of inputs (IOs, parameters).
+
+Once you add the wanted ``Overlays`` and place them into a new ``TestHarness``, you can add a new set of harness/io binders to connect to them.
+This is shown in ``fpga/src/main/scala/vcu118/HarnessBinders.scala``.
+For more information on harness and IO binders, refer to :ref:`IOBinders and HarnessBinders`.
+
+An example of a more complicated design using new ``Overlays`` can be viewed in ``fpga/src/main/scala/vcu118/bringup/``.

docs/Simulation/index.rst

@@ -1,16 +1,18 @@
 Simulation
 =======================
 
-Chipyard supports two classes of simulation:
+Chipyard supports three classes of simulation:
 
-#. Software RTL simulation using commercial or open-source (Verilator) RTL simulators 
+#. Software RTL simulation using commercial or open-source (Verilator) RTL simulators
 #. FPGA-accelerated full-system simulation using FireSim
+#. FPGA prototyping on ``fpga-shells`` platforms
 
 Software RTL simulators of Chipyard designs run at O(1 KHz), but compile
-quickly and provide full waveforms. Conversly, FPGA-accelerated simulators run
+quickly and provide full waveforms. Conversely, FPGA-accelerated simulators and FPGA prototyping 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.
+visibility. However, FPGA-accelerated simulators differ from FPGA prototyping by providing deterministic
+cycle-accurate results.
 
 Click next to see how to run a simulation.
 
@@ -20,4 +22,5 @@ Click next to see how to run a simulation.
 
    Software-RTL-Simulation
    FPGA-Accelerated-Simulation
+   FPGA-Prototyping
 

fpga/src/main/scala/vcu118/Configs.scala

@@ -48,6 +48,7 @@ class WithSystemModifications extends Config((site, here, up) => {
   case ExtMem => up(ExtMem, site).map(x => x.copy(master = x.master.copy(size = site(VCU118DDRSize))))
 })
 
+// DOC include start: AbstractVCU118 and Rocket
 class AbstractVCU118Config extends Config(
   new WithUART ++
   new WithSPISDCard ++
@@ -72,6 +73,7 @@ class AbstractVCU118Config extends Config(
 class RocketVCU118Config extends Config(
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new AbstractVCU118Config)
+// DOC include end: AbstractVCU118 and Rocket
 
 class BoomVCU118Config extends Config(
   new WithFPGAFrequency(75) ++

fpga/src/main/scala/vcu118/TestHarness.scala

@@ -70,10 +70,12 @@ class VCU118FPGATestHarness(override implicit val p: Parameters) extends VCU118S
 
   /*** UART ***/
 
+// DOC include start: UartOverlay
   // 1st UART goes to the VCU118 dedicated UART
 
   val io_uart_bb = BundleBridgeSource(() => (new UARTPortIO(dp(PeripheryUARTKey).head)))
   dp(UARTOverlayKey).head.place(UARTDesignInput(io_uart_bb))
+// DOC include end: UartOverlay
 
   /*** SPI ***/