Skip to content

README.md

Latest commit

 

History

History
173 lines (153 loc) · 7.75 KB

README.md

File metadata and controls

173 lines (153 loc) · 7.75 KB
Raw

SPDX-License-Identifier: Apache-2.0


Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Caliptra FPGA Guide

FPGA provides a fast environment for software development and testing that uses Caliptra RTL. The FPGA's Programmable Logic is programmed with the Caliptra RTL and FPGA specific SoC wrapper logic including a connection to the Processing System AXI bus. The Processing System ARM cores then act as the SoC Security Processor with memory mapped access to Caliptra's public register space.

Requirements:

  • Vivado
    • Version v2022.2 or 2024.2
  • PetaLinux Tools
    • Version must match Vivado
  • FPGA
    • VCK190
    • VMK180 will be supported soon.

Versal

Processing system one time setup:

  1. Download VCK190 SD card image and install to a microSD card. The Versal is packaged with a blank microSD card in the box that can be used for the OS.
    • Insert the SD card into the slot on top of the board.
      • The slot below the board is for the System Controller and the card there should be left inserted.
    • https://ubuntu.com/download/amd-xilinx
  2. Configure SW1 to boot from SD1: Image
    • Mode SW1[4:1]: OFF, OFF, OFF, ON
  3. Boot from the SD card.
    • Initial boot requires connecting over serial. The first serial port is for the PS. See below for settings.
    • Initial credentials
      • User: ubuntu Pass: ubuntu
    • Install software dependencies - Do not update the system 
      sudo apt update
sudo apt install make gcc
    • Install rustup using Unix directions: https://rustup.rs/#
    • [Optional] Assign a hostname for SSH access.
    • [Optional] Save uboot environment variables to avoid the MAC being randomized each boot.
      • When connected to the serial port interrupt uboot at the message "Hit any key to stop autoboot: 0"
      • Issue 'saveenv' command to uboot, which creates an env file in the boot partition for use in subsequent boots.

Serial port configuration:

The USB Type-C connecter J207 provides UART and JTAG access to the board.

  1. VCK190 JTAG chain
  2. PS UART (First COM port)
  3. PL UART (Currently unused)
  4. System Controller UART (Third COM port)

Serial port settings for the PS UART:

  • Speed: 115200
  • Data bits: 8
  • Stop bits: 1
  • Parity: None
  • Flow control: None

FPGA build steps:

The FPGA build process uses Vivado's batch mode to procedurally create the Vivado project using fpga_configuration.tcl. This script provides a number of configuration options for features that can be enabled using "-tclargs OPTION=VALUE OPTION=VALUE"

Option Purpose
BUILD Automatically start building the FPGA.
GUI Open the Vivado GUI.
ITRNG Enable Caliptra's ITRNG.
CG_EN Removes FPGA optimizations and allows clock gating.
RTL_VERSION RTL directory under hw/. latest or 1.0.
BOARD VCK190 or VMK180 (TODO: VMK180 not fully enabled)
  • Build FPGA image without GUI
    • vivado -mode batch -source fpga_configuration.tcl -tclargs BUILD=TRUE
    • Above command creates a Vivado Hardware Platform located at: caliptra_build/caliptra_fpga.xsa
  • Launch Vivado with GUI
    • vivado -mode batch -source fpga_configuration.tcl -tclargs GUI=TRUE
    • Run Synthesis: launch_runs synth_1
    • [Optional] Set Up Debug signals on Synthesized Design
    • Run Implementation: launch_runs impl_1
    • Generate Device Image: write_device_image $outputDir/caliptra_fpga
    • Export hardware: write_hw_platform -fixed -include_bit -force -file $outputDir/caliptra_fpga.xsa

Build boot.bin:

  • Source PetaLinux tools from the PetaLinux installation directory. PetaLinux Tools must match Vivado version
    • source settings.sh
  • Execute create_boot_bin.sh to create a BOOT.BIN
    • ./create_boot_bin.sh /path/to/caliptra_fpga_project_bd_wrapper.xsa
  • (Optional) After the BOOT.BIN is created once, update_boot_bin.sh can be used to incorporate a new xsa.
    • ./update_boot_bin.sh /path/to/caliptra_fpga_project_bd_wrapper.xsa
  • Copy petalinux_project/images/linux/BOOT.BIN to the boot partition as boot1900.bin
    • If the Ubuntu image is booted, it will mount the boot partition at /boot/firmware/
    • If boot1900.bin fails to boot the system will fallback to the default boot1901.bin
    sudo su
cp BOOT.BIN /boot/firmware/boot1900.bin
reboot
  • Verify the correct image is loaded
    • fpga_magic (0xA4010000) contains 0x52545043.
    • fpga_version (0xA4010004) contains the hash of the git HEAD commit.

Running Caliptra tests from the FPGA:

# Install dependencies
sudo apt update
sudo apt install make gcc
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Clone this repo
git clone https://github.com/chipsalliance/caliptra-sw.git
git submodule init
git submodule update
# Compile and install the kernel module
sudo ./hw/fpga/setup_fpga.sh

CPTRA_UIO_NUM=0 cargo test --features=fpga_realtime,itrng -p caliptra-test smoke_test::smoke_test

Processing System - Programmable Logic interfaces

FPGA Wrapper Registers

Versal Memory Map

IP/Peripheral Address size Start address End address
ROM Backdoor 96 KiB 0xB000_0000 0xB001_7FFF
FPGA Wrapper Registers 8 KiB 0xA401_0000 0xA401_1FFF
Caliptra 1 MiB 0xA410_0000 0xA41F_FFFF

JTAG debug

Requirements:

  • Security state must have either debug_locked == false or lifecycle == manuf.
  • Set "debug = true" in firmware profile to provide line information to GDB.
  • openocd 0.12.0 (must be configured with --enable-sysfsgpio)
  • gdb-multiarch

Debugger launch procedure

Caliptra's JTAG pins are directly connected to EMIO GPIO pins bridging the PS and PL. OpenOCD is run on the ARM core and uses SysFs to interface with the GPIO pins.

  1. Invoke OpenOCD server
    • sudo openocd --file caliptra-sw/hw/fpga/openocd_caliptra.txt
  2. Connect client(s) for debug
    • GDB: gdb-multiarch [bin] -ex 'target remote localhost:3333'
    • Telnet: telnet localhost 4444

Caliptra SoC interface registers

Over Telnet connection to OpenOCD: riscv.cpu riscv dmi_read [addr]

JTAG testing

Test requirements for both OpenOCD and GDB:

  • JTAG port is accessible when debug_locked == true or lifecycle == manufacturing. The port is inaccessible otherwise.
  • Read access to ROM space using 8, 16, 32, and 64 bit reads.
  • Read and write access to DCCM using 8, 16, 32, and 64 bit accesses.
  • Access to ICCM using 32 and 64 bit reads, 32 bit writes.
  • Access to VEER core registers.
  • HW and SW breakpoints halt the CPU.
  • Watchpoints on DCCM and Caliptra register access halt the CPU.

Test requirements exclusive to GDB:

  • Basic commands all work (step, next, frame, info, bt, ni, si, etc.).

Test requirements exclusive to OpenOCD:

  • Basic commands all work (reg, step, resume, etc.).
  • Access to VEER CSRs.
  • Access to Debug Module registers.
  • Caliptra registers exposed to JTAG RW/RO status matches.