Merge remote-tracking branch 'origin/dev' into hammer-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:`Simulation/Software-RTL-Simulation: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:`Simulation/Software-RTL-Simulation:Synopsys VCS (License Required)` for more information.
@@ -124,6 +124,15 @@ Sims
   In order to use FireSim, the repository must be cloned and executed on AWS instances.
   See :ref:`Simulation/FPGA-Accelerated-Simulation:FireSim` for more information.
 
+Prototyping
+-------------------------------------------
+
+**FPGA Prototyping**
+  FPGA prototyping is supported in Chipyard using SiFive's ``fpga-shells``.
+  Some examples of FPGAs supported are the Xilinx Arty 35T and VCU118 boards.
+  For a fast and deterministic simulation with plenty of debugging tools, please consider using the :ref:`FireSim` platform.
+  See :ref:`Prototyping Flow` for more information on FPGA prototypes.
+
 VLSI
 -------------------------------------------
 

docs/Prototyping/Arty.rst

@@ -0,0 +1,26 @@
+Running a Design on Arty
+========================
+
+Basic Arty Design
+-----------------
+
+The default Xilinx Arty 35T harness is setup to have JTAG available over the board's PMOD pins, and UART available over its FTDI serial USB adapter. The pin mappings for JTAG signals are identical to those described in the `SiFive Freedom E310 Arty 35T Getting Started Guide <https://static.dev.sifive.com/SiFive-E310-arty-gettingstarted-v1.0.6.pdf>`__.
+The JTAG interface allows a user to connect to the core via OpenOCD, run bare-metal applications, and debug these applications with gdb. UART allows a user to communicate with the core over a USB connection and serial console running on a PC.
+To extend this design, a user may create their own Chipyard configuration and add the ``WithArtyTweaks`` located in ``fpga/src/main/scala/arty/Configs.scala``.
+Adding this config. fragment will enable and connect the JTAG and UART interfaces to your Chipyard design.
+
+.. literalinclude:: ../../fpga/src/main/scala/arty/Configs.scala
+    :language: scala
+    :start-after: DOC include start: AbstractArty and Rocket
+    :end-before: DOC include end: AbstractArty and Rocket
+
+Future peripherals to be supported include the Arty 35T SPI Flash EEPROM, and I2C/PWM/SPI over the Arty 35T GPIO pins. These peripherals are available as part of sifive-blocks.
+
+Brief Implementation Description and Guidance for Adding/Changing Xilinx Collateral
+-----------------------------------------------------------------------------------
+
+Like the VCU118, the basis for the Arty 35T design is the creation of a special test harness that connects the external IO (which exist as Xilinx IP blackboxes) to the Chipyard design.
+This is done with the ``ArtyTestHarness`` in the basic default Arty 35T target. However, unlike the ``VCU118TestHarness``, the ``ArtyTestHarness`` uses no ``Overlays``, and instead directly connects chip top IO to the ports of the external IO blackboxes, using functions such as ``IOBUF`` provided by ``fpga-shells``.
+Unlike the VCU118 and other more complicated test harnesses, the Arty 35T Vivado collateral is not generated by ``Overlays``, but rather are a static collection of ``create_ip`` and ``set_properties`` statements located in the files within ``fpga/fpga-shells/xilinx/arty/tcl`` and ``fpga/fpga-shells/xilinx/arty/constraints``.
+If the user wishes to re-map FPGA package pins to different harness-level IO, this may be changed within ``fpga/fpga-shells/xilinx/arty/constraints/arty-master.xdc``. The addition of new Xilinx IP blocks may be done in ``fpga-shells/xilinx/arty/tcl/ip.tcl``, mapped to harness-level IOs in ``arty-master.xdc``, and wired through from the test harness to the chip top using ``HarnessBinders`` and ``IOBinders``.
+Examples of a simple ``IOBinder`` and ``HarnessBinder`` for routing signals (in this case the debug and JTAG resets) from the core to the test harness are the ``WithResetPassthrough`` and ``WithArtyResetHarnessBinder``.

docs/Prototyping/General.rst

@@ -0,0 +1,70 @@
+General Setup and Usage
+==============================
+
+Sources and Submodule Setup
+---------------------------
+
+All FPGA prototyping-related collateral and sources are located in the ``fpga`` top-level Chipyard directory.
+This includes the ``fpga-shells`` submodule and the ``src`` directory that hold both Scala, TCL and other collateral.
+However, the ``fpga-shells`` submodule repository is not initialized by default.
+To initialize the ``fpga-shells`` submodule repository, run the included initialization script from the Chipyard top-level directory:
+
+.. code-block:: shell
+
+    # in the chipyard top level folder
+    ./scripts/init-fpga.sh
+
+Generating a Bitstream
+----------------------
+
+Generating a bitstream for any FPGA target using Vivado is similar to building RTL for a software RTL simulation.
+Similar to a software RTL simulation (:ref:`Simulating A Custom Project`), you can run the following command in the ``fpga`` directory to build a bitstream using Vivado:
+
+.. code-block:: shell
+
+    make SBT_PROJECT=... MODEL=... VLOG_MODEL=... MODEL_PACKAGE=... CONFIG=... CONFIG_PACKAGE=... GENERATOR_PACKAGE=... TB=... TOP=... BOARD=... FPGA_BRAND=... bitstream
+
+    # or
+
+    make SUB_PROJECT=<sub_project> bitstream
+
+The ``SUB_PROJECT`` make variable is a way to meta make variable that sets all of the other make variables to a specific default.
+For example:
+
+.. code-block:: shell
+
+    make SUB_PROJECT=vcu118 bitstream
+
+    # converts to
+
+    make SBT_PROJECT=fpga_platforms MODEL=VCU118FPGATestHarness VLOG_MODEL=VCU118FPGATestHarness MODEL_PACKAGE=chipyard.fpga.vcu118 CONFIG=RocketVCU118Config CONFIG_PACKAGE=chipyard.fpga.vcu118 GENERATOR_PACKAGE=chipyard TB=none TOP=ChipTop BOARD=vcu118 FPGA_BRAND=... bitstream
+
+Some ``SUB_PROJECT`` defaults are already defined for use, including ``vcu118`` and ``arty``.
+These default ``SUB_PROJECT``'s setup the necessary test harnesses, packages, and more for the Chipyard make system.
+Like a software RTL simulation make invocation, all of the make variables can be overridden with user specific values (ex. include the ``SUB_PROJECT`` with a ``CONFIG`` and ``CONFIG_PACKAGE`` override).
+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 bitstream
+
+That command will build the RTL and generate a bitstream using Vivado.
+The generated bitstream will be located in your designs specific build folder (``generated-src/<LONG_NAME>/obj``).
+However, like a software RTL simulation, you can also run the intermediate make steps to just generate Verilog or FIRRTL.
+
+Debugging with ILAs on Supported FPGAs
+--------------------------------------
+
+ILA (integrated logic analyzers) can be added to certain designs for debugging relevant signals.
+First, open up the post synthesis checkpoint located in the build directory for your design in Vivado (it should be labeled ``post_synth.dcp``).
+Then using Vivado, add ILAs (and other debugging tools) for your design (search online for more information on how to add an ILA).
+This can be done by modifying the post synthesis checkpoint, saving it, and running ``make ... debug-bitstream``.
+This will create a new bitstream called ``top.bit`` in a folder named ``generated-src/<LONG_NAME>/debug_obj/``.
+For example, running the bitstream build for an added ILA for a BOOM config.:
+
+.. code-block:: shell
+
+    make SUB_PROJECT=vcu118 CONFIG=BoomVCU118Config debug-bitstream
+
+.. IMPORTANT:: For more extensive debugging tools for FPGA simulations including printf synthesis, assert synthesis, instruction traces, ILAs, out-of-band profiling, co-simulation, and more, please refer to the :ref:`FireSim` platform.

docs/Prototyping/VCU118.rst

@@ -0,0 +1,60 @@
+Running a Design on VCU118
+==========================
+
+Basic VCU118 Design
+-------------------
+
+The default Xilinx VCU118 harness is setup to have UART, a SPI SDCard, and DDR backing memory.
+This allows it to run RISC-V Linux from an SDCard while piping the terminal over UART to the host machine (the machine connected to the VCU118).
+To extend this design, you can create your own Chipyard configuration and add the ``WithVCU118Tweaks`` 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 to your Chipyard design/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
+
+Brief Implementation Description + More Complicated Designs
+-----------------------------------------------------------
+
+The basis for a VCU118 design revolves around creating a special test harness to connect the external IOs to your Chipyard design.
+This is done with the ``VCU118TestHarness`` in the basic default VCU118 FPGA target.
+The ``VCU118TestHarness`` (located in ``fpga/src/main/scala/vcu118/TestHarness.scala``) uses ``Overlays`` that connect to the VCU118 external IOs.
+Generally, the ``Overlays`` take an IO from the ``ChipTop`` (labeled as ``topDesign`` in the file) when "placed" and connect it to the external IO and generate necessary Vivado collateral.
+For example, the following shows a UART ``Overlay`` being "placed" into the design with a IO input called ``io_uart_bb``.
+
+.. 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 IO from the ``ChipTop``/``topDesign`` to the ``Overlay``.
+Note that the ``BundleBridgeSource`` can be viewed as a glorified wire (that is defined in the ``LazyModule`` scope).
+This pattern is similar for all other ``Overlays`` in the test harness.
+They must be "placed" and given a set of inputs (IOs, parameters).
+The main exception to this pattern is the ``Overlay`` used to generate the clock(s) for the FPGA.
+
+.. literalinclude:: ../../fpga/src/main/scala/vcu118/TestHarness.scala
+    :language: scala
+    :start-after: DOC include start: ClockOverlay
+    :end-before: DOC include end: ClockOverlay
+
+Without going into too much detail, the clocks overlay is placed in the harness and a PLL node (``harnessSysPLL``) generates the necessary clocks specified by ``ClockSinkNodes``.
+For ease of use, you can change the ``FPGAFrequencyKey`` to change the default clock frequency of the FPGA design.
+
+After the harness is created, the ``BundleBridgeSource``'s must be connected to the ``ChipTop`` IOs.
+This is done with harness binders and io binders (see ``fpga/src/main/scala/vcu118/HarnessBinders.scala`` and ``fpga/src/main/scala/vcu118/IOBinders.scala``).
+For more information on harness binders and io binders, refer to :ref:`IOBinders and HarnessBinders`.
+
+Introduction to the Bringup Platform
+------------------------------------
+
+An example of a more complicated design used for Chipyard test chips can be viewed in ``fpga/src/main/scala/vcu118/bringup/``.
+This example extends the default test harness and creates new ``Overlays`` to connect to a DUT (connected to the FMC port).
+Extensions include another UART (connected over FMC), I2C (connected over FMC), miscellaneous GPIOS (can be connected to anything), and a TSI Host Widget.
+The TSI Host Widget is used to interact with the DUT from the prototype over a SerDes link (sometimes called the Low BandWidth InterFace - LBWIF) and provide access to a channel of the FPGA's DRAM.
+
+.. Note:: Remember that since whenever a new test harness is created (or the config changes, or the config packages changes, or...), you need to modify the make invocation.
+    For example, ``make SUB_PROJECT=vcu118 CONFIG=MyNewVCU118Config CONFIG_PACKAGE=this.is.my.scala.package bitstream``.
+    See :ref:`Generating a Bitstream` for information on the various make variables.

docs/Prototyping/index.rst

@@ -0,0 +1,16 @@
+Prototyping Flow
+================
+
+Chipyard supports FPGA prototyping for local FPGAs supported by `fpga-shells <https://github.com/sifive/fpga-shells>`__.
+This includes popular FPGAs such as the Xilinx VCU118 and the Xilinx Arty 35T board.
+
+.. Note:: While ``fpga-shells`` provides harnesses for other FPGA development boards such as the Xilinx VC707 and some MicroSemi PolarFire, only harnesses for the Xilinx VCU118 and Xilinx Arty 35T boards are currently supported in Chipyard.
+    However, the VCU118 and Arty 35T examples demonstrate how a user may implement support for other harnesses provided by fpga-shells.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Prototyping Flow:
+
+   General
+   VCU118
+   Arty

docs/Simulation/index.rst

@@ -3,14 +3,14 @@ Simulation
 
 Chipyard supports two 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
 
 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 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.
 
 Click next to see how to run a simulation.
 
@@ -20,4 +20,3 @@ Click next to see how to run a simulation.
 
    Software-RTL-Simulation
    FPGA-Accelerated-Simulation
-

docs/index.rst

@@ -45,6 +45,8 @@ Table of Contents
 
    TileLink-Diplomacy-Reference/index
 
+   Prototyping/index
+
 
 Indices and tables
 ==================