README.adoc

DE10Pro-CHERI-BGAS Top-Level Repository

The DE10Pro-cheri-bgas repository to provides FPGA bitfiles for the CHERI-BGAS project.

It includes the Stratix 10 Quartus project, IP configuration, toplevel entity verilog, and signal tap configuration files, necessary for synthesis of a configuration image for the Terasic DE10Pro SX board. At the moment, the project uses Quartus 23.2pro.

This repository also includes RTL sources under the bluespec/ folder, where various git submodules are used and suplemented with a few .bsv files providing some "toplevel glue" as well as a minimal simulation framework.

Contents

1. Quick start

1.1. Get submodules

To begin with, clone all required git submodules recursively:

$ git submodule update --init --recursive

Currently, this repo uses the following direct submodules:

• bluespec/BSVFan

  A fan controller device for the DE10 board.

• bluespec/DE10Pro-bsv-shell

  A Bluespec SystemVerilog Interface definition for DE10Pro projects with a set of sub-interfaces exposing some of the devices available on the board to the code implementing the interface.

• bluespec/Recipe

  A BSV library providing a way to easily build state machines.

• bluespec/Toooba

  A CHERI-enabled Out-of-Order RISC-V Core.

• bluespec/VirtualDevice

  A Bluespec AXI component that intended to act as a virtual device.

• bluespec/sim-utils/cheri-bgas-fuse-devfs

  A fuse filesystem to expose as fmem devices the available devices from a DE10-cheri-bgas simulator.

• bluespec/sim-utils/forever-splice

  A utility program continuously consuming from a unix fifo and producing into another.

• bluespec/sim-utils/jtagvpi_to_fmemdmi

  A utility converting gdb commands received over jtag as vpi packets to RISC-V "DMI" Debug Module Interface packets over fmem.

• software/bare-metal-de10-cheri-bgas

  A basic bare-metal setup to write software for the DE10-cheri-bgas platform.

• vipbundle

  A tool to package a verilog module into a Quartus system-builder component.

This repo also indirectly relies on (among others) the following repositories:

• WindCoreInterface

• cheri-cap-lib

• TagController

• RISCV_HPM_Events

• BlueStuff

• BlueAXI4

• BlueUnixBridges

• BlueBasics

1.2. Build a Stratix 10 bitfile

Building the vipbundle tool requires a working installation of the ghc haskell compiler with the regex-tdfa haskell library. It will be built automatically as part of the overall build process for the FPGA image.

Additionally, you will need a working installation of Quartus 23.2pro and a bluespec compiler.

You can then run:

$ make synthesize

to generate a output_files/DE10Pro-cheri-bgas.sof Stratix 10 FPGA bitfile.

1.2.1. Generate .rbf bitfile slices and embed a bootloader

The bitfiles generated embed both a soft RISCV core and an ARM Hard Processor System (HPS). The bootloader code for the HPS can be embedded into a bitfile. To do so, you can run

$ BOOTLOADER=some/bootloader/ihex make gen-rbf

or simply

$ make gen-rbf

once an FPGA bitfile has been successfully generated. This will generate two .rbf slices out of the .sof, one for the base hps system configuration, and one core configuration. The BOOTLOADER environment variable defaults to $(CURDIR)/software/uboot_build/u-boot-socfpga/spl/u-boot-spl-dtb.ihex.

2. Intel Stratix 10 Hard Processor System interactions

Software running on the HPS can interact with the RISCV system on the FPGA in a variety of ways. The HPS can use a "lightweight" 32-bit AXI4 port as well as a 128-bit AXI4 port to perform FPGA accesses. As documented by Intel, several windows in the HPS’s address space can be used to perform these accesses:

• FPGA_bridge_lwsoc2fpga_2M: 0xf900_0000 → 0xf91f_ffff

• FPGA_bridge_soc2fpga_1G_default: 0x8000_0000 → 0xbfff_ffff

• FPGA_bridge_soc2fpga_512M_default: 0xc000_0000 → 0xdfff_ffff

• FPGA_bridge_soc2fpga_1G: 0x20_0000_0000 → 0x20_3fff_ffff

• FPGA_bridge_soc2fpga_512M: 0x20_4000_0000 → 0x20_5fff_ffff

• FPGA_bridge_soc2fpga_2.5G: 0x20_6000_0000 → 0x20_ffff_ffff

Additionally, the RISCV system is provided a window into the HPS system’s memory map via adedicated 128-bit fpga2hps AXI4 slave port.

2.1. lwsoc2fpga "lightweight" AXI4 master port

The 32-bit lwsoc2fpga "lightweight" AXI4 master port is used for accesses in the 0xf900_0000 to 0xf91f_ffff range. Exposed through these addresses on the FPGA side in the RISCV system are the following:

• 0xf900_0000 → 0xf900_0fff: Debug Unit

• 0xf900_1000 → 0xf900_1fff: Interrupt lines

• 0xf900_2000 → 0xf900_2fff: Others (not yet clear what exactly…​)

• 0xf900_3000 → 0xf900_3fff: "fake" 16550

• 0xf900_4000 → 0xf900_4fff: h2f address controller

2.2. soc2fpga AXI4 master port

The 128-bit soc2fpga AXI4 master port is used for accesses in the ranges documented above. It is a 32-bit address port which exposes a 4GB wide window into the same 64-bit address memory map perceived by the RISCV core on the FPGA. The device exposed via the lwsoc2fpga port at 0xf900_4000 → 0xf900_4fff allows software on the FPGA to specify the upper 32 bits of a full 64-bit address and effectively slide the available 4GB window.

2.3. fpga2hps AXI4 slave port

The 128-bit fpga2hps AXI4 slave port provides the RISCV softcore system with cache-coherent access to the HPS memory map. See the Intel Stratix 10 Hard Processor System Technical Reference Manual for further details.

3. Simulation framework

A minimal simulation framework is provided under the bluespec/ directory. See here for further information.