From 255e88fe8f8a0ee5e2b648403d0d6b872d75e1d1 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Thu, 5 Nov 2020 17:06:34 -0800 Subject: [PATCH] Initial outline of FPGA prototyping docs --- docs/Chipyard-Basics/Chipyard-Components.rst | 11 ++- docs/Simulation/FPGA-Prototyping.rst | 87 ++++++++++++++++++++ docs/Simulation/index.rst | 11 ++- fpga/src/main/scala/vcu118/Configs.scala | 2 + fpga/src/main/scala/vcu118/TestHarness.scala | 2 + 5 files changed, 107 insertions(+), 6 deletions(-) create mode 100644 docs/Simulation/FPGA-Prototyping.rst diff --git a/docs/Chipyard-Basics/Chipyard-Components.rst b/docs/Chipyard-Basics/Chipyard-Components.rst index c24f81ed..1d19a65f 100644 --- a/docs/Chipyard-Basics/Chipyard-Components.rst +++ b/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 ------------------------------------------- diff --git a/docs/Simulation/FPGA-Prototyping.rst b/docs/Simulation/FPGA-Prototyping.rst new file mode 100644 index 00000000..eab33d35 --- /dev/null +++ b/docs/Simulation/FPGA-Prototyping.rst @@ -0,0 +1,87 @@ +FPGA Prototyping +============================== + +FPGA Prototyping +----------------------- + +Chipyard supports FPGA prototyping for local FPGAs supported under ``fpga-shells`` . +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= 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/``. diff --git a/docs/Simulation/index.rst b/docs/Simulation/index.rst index c15283d3..24099bfb 100644 --- a/docs/Simulation/index.rst +++ b/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 diff --git a/fpga/src/main/scala/vcu118/Configs.scala b/fpga/src/main/scala/vcu118/Configs.scala index f55c9520..6822b251 100644 --- a/fpga/src/main/scala/vcu118/Configs.scala +++ b/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) ++ diff --git a/fpga/src/main/scala/vcu118/TestHarness.scala b/fpga/src/main/scala/vcu118/TestHarness.scala index d5a5481e..05e1e59d 100644 --- a/fpga/src/main/scala/vcu118/TestHarness.scala +++ b/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 ***/