axiom-beta-rfdev

Note: This repository contains all the source code produced by me under GSoC 2020 with apertus° Association. For detailed project report, please read GSoC2020_final_report.pdf in this repository.

A Linux Kernel Driver for programming/debugging the Lattice MachXO2 FPGAs (used as routing fabrics) in AXIOM Beta Main Board. The driver integrates with Linux FPGA Manager Framework to allow easy programming of MachXO2's SRAM.

Here is an overview of the setup:
Zynq SoC <--- I2C ---> PIC16 MCU <--- JTAG ---> MachXO2 FPGA

Linux runs on hardened ARM cores in Zynq SoC, which is where the driver comes in. PIC16 responds to a range of I2C commands and translates them into JTAG commands for MachXO2.

Features

• Upload a compressed bitstream (produced by Lattice Diamod tools) into MachXO2's SRAM
  # echo bitstream.bit > /sys/class/fpga_manager/fpga#/firmware where,
  
  • fpga# could be fpga0, fpga1 etc.
  • bitstream.bit must be in FPGA Manager's search path (/lib/firmware by default)
• sysfs entry to read out idcode
  $ cat /sys/class/fpga_manager/fpga#/idcode
• sysfs entry to read out status register
  $ cat /sys/class/fpga_manager/fpga#/stat
• sysfs entry to show human readable string for status
  $ cat /sys/class/fpga_manager/fpga#/statstr
• sysfs entry to show md5 digest of the uploaded bitstream
  $ cat /sys/class/fpga_manager/fpga#/digest
• sysfs entry to read out traceid (unique fpga identifier)
  $ cat /sys/class/fpga_manager/fpga#/traceid
• sysfs entry to read out usercode
  $ cat /sys/class/fpga_manager/fpga#/usercode
• RFWest and RFEast can be used seperately for AXIOM Betas with both old and new power board versions
• A User API based on ioctl is added which exposes a JTAG interface from the FPGAs
  • Can be used by an application like OpenOCD to do SVF replays for programming or debugging
    
  • The two devices can be accessed as: /dev/rfjtag0 and /dev/rfjtag1
  • The code was made generic to allow registration of multiple MachXO2 devices in the setup (as /dev/rfjtag#) and configurable through devicetree entries

Following ioctl commands are defined:

JTAG_SIOCSTATE    -> transit to given tap state
JTAG_GIOCENDSTATE -> get current tap state
JTAG_IOCXFER      -> send SIR/SDR transaction

Requirements

Appropriate devicetree overlay must be loaded in AXIOM Beta:

• dt-overlay/pic_rf_mux_overlay.dts for power board with PCA9540 mux
  
• dt-overlay/pic_rf_mux_rst_overlay.dts for power board with PCA9543 mux
  
• dt-overlay/pic_rf_switch_overlay.dts for power board with TS3A4751 analog switch

Run the following scripts before loading the driver (in firmware 2.0):

# the scripts directory in this repo
cd scripts

# initialize power and load the icsp bitstream into microzed's fpga
sudo ./opt/axiom-firmware/software/scripts/axiom_prep_iscp.sh

# pull up the #MCLR lines of both the PIC16s
sudo python pull_up_reset.py

# load the appropriate device tree overlay
sudo ./load_overlay.sh ../dt-overlays/pic_rf_switch_overlay.dts

# configure the jtag out ports of both the PIC16s
sudo python jtag_on.py

OpenOCD Usage

The patch for OpenOCD can be found inside openocd-patch directory in this repo.
After applying the patch configure OpenOCD with --enable-rfdev-jtag=yes option and build.
A sample .cfg file for OpenOCD then will look like this:

# select the driver
adapter driver rfdev_jtag

# specify the device file
rfdev_set_device /dev/rfjtag0

# speed must be specified but is not used
adapter speed 1

Then run with something like:
./openocd -f openocd.cfg -c init -c "svf count.svf"

Build Instructions

1. git clone --recursive https://github.com/apertus-open-source-cinema/axiom-firmware
2. cd axiom-firmware
3. ./makefiles/docker-make.sh build/linux-v5.2.14.git/arch/arm/boot/zImage where, 5.2.14 should be replaced with latest kernel version used in AXIOM Beta (see here: axiom-firmware/makefiles/host/bootfs.mk). This command should build the kernel once.
4. cd build
5. git clone https://github.com/Swaraj1998/axiom-beta-rfdev (this repo)
6. ../makefiles/docker-make.sh build-shell (get a shell inside the build container)
   
   Inside the build-shell:
7. cd build/axiom-beta-rfdev (you just cloned it)
8. make (or make clean)

Note: make native & make clean_native compiles against currently running kernel in your system (just used for testing build)

- Comment out the call to reset_fpga() inside rfdev_remove() in rfdev.c before compiling to avoid triggering a reset on driver unload