Create new prototyping section | Address some comments | Small clarifications

docs/Prototyping/Arty.rst

@@ -0,0 +1,28 @@
+Running a Design on Arty
+========================
+
+Basic Design
+------------
+
+The default Arty FPGA target design is setup to have JTAG, UART, SPI, and I2C available over the board's GPIO pins.
+The pin mappings of these interfaces are identical to those described in the `SiFive Freedom E310 Arty 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 over OpenOCD, run bare-metal applications, and debug using gdb.
+To extend this design, you can create your 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, UART, SPI, and I2C interfaces to your Chipyard design/config.
+
+.. 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's SPI Flash EEPROM.
+
+Brief Implementation Description and Guidance for Adding/Changing Xilinx Collateral
+-----------------------------------------------------------------------------------
+
+The basis for the Arty design is the creation of a special test harness that connects the external FPGA IO (which exist as Xilinx IP blackboxes) to the Chipyard design.
+This is done with the ``ArtyTestHarness`` in the basic default Arty target.
+However, unlike the more complicated ``VCU118TestHarness``, the ``ArtyTestHarness`` uses no ``Overlays``, and instead directly connects ``ChipTop`` IO to the ports of the external FPGA IO blackboxes, using functions such as ``IOBUF`` provided by ``fpga-shells``.
+Unlike the VCU118 and other more complicated test harnesses, the Arty's 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 ``ChipTop`` using ``HarnessBinders`` and ``IOBinders``.

docs/Prototyping/General.rst

@@ -0,0 +1,68 @@
+General Setup and Usage
+==============================
+
+Sources and Submodule Setup
+---------------------------
+
+All FPGA 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=... bit
+
+    # or
+
+    make SUB_PROJECT=<sub_project> bit
+
+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 bit
+
+    # 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 bit
+
+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 bit
+
+That command will build the RTL and generate a bitstream using Vivado.
+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
+--------------------------------------
+
+Adding an ILA (integrated logic analyzer) 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``.
+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
+
+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,55 @@
+Running a Design on VCU118
+==========================
+
+Basic Design
+------------
+
+The default VCU118 FPGA target design 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`.
+
+An example of a more complicated design using new ``Overlays`` can be viewed in ``fpga/src/main/scala/vcu118/bringup/``.
+This example extends the default test harness and creates new ``Overlays`` to connect to the FMC port.
+
+.. 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 bit``.
+    See :ref:`Making a Bitstream` for information on the various make variables.

docs/Prototyping/index.rst

@@ -0,0 +1,17 @@
+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 board.
+FPGA prototyping allows for orders-of-magnitude faster speeds than software RTL simulators at the cost of slower compile times and less design introspection.
+
+.. Note:: While ``fpga-shells`` also supports Xilinx VC707 and some MicroSemi PolarFire boards, currently only the VCU118 and Arty boards are explicitly supported in Chipyard.
+    However, using the VCU118/Arty examples would be useful to see how to implement VC707/PolarFire support.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Prototyping Flow:
+
+   General
+   VCU118
+   Arty