128 lines
7.3 KiB
ReStructuredText
128 lines
7.3 KiB
ReStructuredText
FPGA Prototyping
|
|
==============================
|
|
|
|
FPGA Prototyping
|
|
----------------
|
|
|
|
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 RTL-level simulation at orders-of-magnitude faster speeds than software RTL simulators at the cost of slower compile times.
|
|
|
|
.. 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.
|
|
|
|
Sources and Submodule Setup
|
|
---------------------------
|
|
|
|
All FPGA related collateral and sources are located in the ``fpga`` top-level Chipyard folder.
|
|
This includes ``fpga-shells`` and the ``src`` folders that hold both Scala, TCL and other collateral.
|
|
However, the ``fpga-shells`` repository is not initialized by default.
|
|
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 target 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:
|
|
|
|
.. 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.
|
|
Like a software RTL simulation make invocation, all of the make variables can be overridden with user specific values (i.e. 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.
|
|
|
|
Running a Design on Arty
|
|
------------------------
|
|
|
|
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.
|
|
|
|
Debugging with ILAs
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Adding an ILA can be added to the design 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).
|
|
After the changes are made, save the checkpoint and run the make invocation with the ``debug-bitstream`` target:
|
|
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.
|