---- ARCHIVED REPOSITORY ----

The CEP now resides here here.

Common Evaluation Platform v4.2

<img src="./cep_docs/cep_logo.jpg" width="375" height="159"> Copyright 2022 Massachusetts Institute of Technology <img src="./cep_docs/cep_architecture.jpg" width="1114" height="450"> <img src="./cep_docs/related_logos.jpg" width="442" height="120">

The Common Evaluation Platform (CEP) is an SoC design that contains only license-unencumbered, freely available components. The CEP includes a range of accelerator cores coupled with a key delivery mechanism, and parametrically-defined challenge modules which can be synthesized to support developmental testing. The implementation of the CEP includes a comprehensive verification environment to ensure modifications do not impede intended functionality. It is intended to be targeted to either an FPGA or ASIC implementation.

Please check the CEP changelog for release history.

Beginning with CEP v4.0, the platform has been ported to the UCB Chipyard Framework. The original Chipyard Readme can be found here.

Throughout the CEP READMEs, <CEP_ROOT> refers to the root directory of the cloned CEP repository.

Pre-requisites (validated test/build configurations):

The following items describe the configuration of the system that CEP has been developed and tested on:

Ubuntu 18.04 LTS x86_64 with Modelsim Questa Sim-64 v2019.1 (for co-simulation)
Red Hat Enterprise Linux 7 with Cadence XCELIUMAGILE20.09.001, VMANAGERAGILE20.06.001
Xilinx Vivado 2020.1 (needed for building FPGA targets)
- Plus Digilent Adept Drivers for programming the FPGA target, https://reference.digilentinc.com/reference/software/adept/start?redirect=1#software_downloads)
Terminal emulator (such as minicom)
bash

Other configurations may work, but they have not been explicitly verified.

Instructions on how to modelsim, xcelium, and Vivado are beyond the scope of this README.

Setting up your environment

To build the CEP, several packages and toolsets must be installed and built. The typical steps are listed below. Additional information can be found in the Chipyard Documentation here.

A note about proxies: If your system is behind a proxy, you'll want to ensure your environment is properly configured. Exact details vary by system, but the proxy needs to be available to apt / yum, curl, and sbt (Simple Build Tool for Scala)

If using RHEL7, you need to ensure gcc 7.x.x+ is installed. This can be found in the rhel-workstation-rhscl-7-rpms or rhel-server-rhscl-7-rpms repos, whose available is RHEL subscription dependent. Once the repo is enabled, the appropriate gcc can be installed by running sudo yum install devtoolset-7-gcc-c++. Once installed, you want to run scl enable devtoolset-7 bash (or whatever version you have installed) to ensure g++ maps to the new version.

Install git if not already present on your system
- Ubuntu - sudo apt install git
- RHEL7 - sudo yum install git
Clone the CEP repository, change to the directory of the clone
- git clone https://github.com/mit-ll/CEP.git
Install package dependencies. Copies of these files can also be found in the Chipyard Documentation listed above
- Ubuntu - ./scripts/ubuntu-reqs.sh
- RHEL7 - ./scripts/centos-reqs.sh
Initialize all the git submodules (including FPGA-related submodules). There may be a warning about this not being a true chipyard repository which you can answer yes to.
- ./scripts/init-submodules-no-riscv-tools.sh
- ./scripts/init-fpga.sh
Build the RISC-V Toolchain.
- Depending on your available hardware, you can expedite the build by executing export MAKEFLAGS=-jN prior to running the build script. N is the number of cores you can devote to the build.
- ./scripts/build-toolchains.sh riscv-tools
RHEL7: The chipyard build needs make v4.x or later, which is not included in the default packages. Recommend building from source (https://ftp.gnu.org/gnu/make/). Once installed, you can force the version of make used using the following: MAKE=/usr/local/bin/make ./scripts/build-toolchains.sh riscv-tools
It is advisable to move the compiled toolchain outside of the current repo if you plan to have multiple CEP working directories. Complete directions are beyond the scope of this document, but they do include moving the riscv-tools-install directory and env-riscv-tools.sh file. Modification of the aforementioned file as well as env.sh will required for smooth operation
Sometimes the toolchain build may fail. One may need to run the build several times.
Once the toolchain is built, your want to source the new environment script: source <CEP_ROOT>/env.sh.

Repository Directory Structure

Providing a complete directory structure is impractical, but some items are highlighted here. It is worth noting that most of the structure is inherited from Chipyard.

<CEP_ROOT> 
  |- ./sims/cep_cosim/ -  
  |     Defines the CEP co-simulation evironment for performing "chip" level simulations of the CEP in 
  |     either bare metal or bus functional model (BFM) mode.  
  |- ./generators/mitll-blocks/
  |   |- src/main/scala - Contains all the custom CEP Chisel code
  |   |- src/main/resources/vsrc/ - SystemVerilog / Verilog files associated with the CEP build
  |       |- generated_dsp_code - Location to place the `dft_top.v` and `idft_top.v'
  |       |- opentitan  - Soft-link to the opentitan submodule located at ./opentitan
  |       |- aeees      - Challenge module.  Read the README.md in this directory for more information.
  |       |- auto-fir   - Challenge module.  Read the README.md in this directory for more information.
  |       |- shaaa      - Challenge module.  Read the README.md in this directory for more information.
  |- ./cep_docs - Documents and images unique to the CEP
  |- ./software/baremetal - Examples of bare metal code that can be run on the Arty100T FPGA target
                            independent of the CEP Co-Simulation environment

Building the CEP FPGA

Multiple Chipyard SUB_PROJECTS have been defined for the CEP when targetting FPGA Development boards.

These subprojects define the system configuration and are as follows:

cep_arty100t - Arty100T Development Board

50 MHz Core Frequency
98% LUT Utilization
1x WithNBigCore
CEP Registers
AES Core
Surrogate Root of Trust (SRoT)

cep_vc707 - VC707 Development Board

100 MHz Core Frequency4
11% LUT Utilization
1x WithNBigCore
CEP Registers
AES Core
Surrogate Root of Trust (SRoT)

cep_big_vc707 - VC707 Development Board

100 MHz Core Frequency
70% LUT Utilization
4x WithNBigCores
CEP Registers
AES Core
DES3 Core
FIR Core
IIR Core
DFT Core
IDFT Core
MD5 Core
4x GPS Cores
4x SHA-256 Cores
RSA Core
Surrogate Root of Trust

cep_vcu118 - VCU118 Development Board

100 MHz Core Frequency
5% LUT Utilization
1x WithNBigCore
CEP Registers
AES Core
Surrogate Root of Trust (SRoT)

Assuming the Vivado environment scripts have been sourced within your current shell, the following commands can be used to build and program the FPGA SUB_PROJECT. Programming requires that the digilent drivers have been installed and that you have a USB connection to the JTAG USB-port of you preffered FPGA board.

Default CEP builds can be customized by following the instructions in the Chipyard documentation.

The FPGA boards will configure from FLASH or JTAG based on the state of the MODE jumper. Additional information can be found:

Arty100T - here.
VC707 - here.
VCU118 - here.

cd <REPO_ROOT>/fpga
make SUB_PROJECT=<cep_arty100t | cep_vc707 | cep_vcu118>

./program_<arty100t | vc707 | vcu118>_flash.sh - Create the MCS file & program the development board's flash.  Power needs to be cycled or the *PROG* button needs to be asserted to reboot with the new configuration.

OR

./program_<arty100t | vc707 | vcu118>_jtag.sh - Program the FPGA via JTAG.  System will automatically reset or you can use the *RESET* button.

Building Bare Metal software for the CEP FPGA

The Arty100T shares a single microUSB connector for JTAG and UART, while the VC707 and VCU118 have seperate ports for each.

For the Arty100T, connect a Digilent SD or microSD PMOD board o connector JA. For the VCU118, connect the same to the PMOD connector on the right side of the board. The PMOD connectors can be ordered from Digikey, Digilent, or other distributors.

Additional information can be found here: (https://digilent.com/shop/pmod-sd-full-sized-sd-card-slot/ or https://digilent.com/shop/pmod-microsd-microsd-card-slot/).

As noted, for the Arty100T the microUSB port uses an FTDI chip to provide both JTAG and UART functionality. Your system may differ, but typically the UART shows up as /dev/ttyUSB0 or /dev/ttyUSB1. UART settings are 115200baud, 8N1 and should be visible to any terminal program. Both HW and SW flow control should be disabled.

It is worth noting that minicom enables HW flow control by default.

Once released from reset, the CEP's bootrom will read the baremetal executable from the SD card, cop

CEP

Install / Use

README