Overview

This project presents an example of how one of the HPS SPI Master Controller signals can be routed through the FPGA fabric to the FPGA pins. This can be useful when there are not enough dedicated HPS pins available. The disadvantage is that the specific SPI controller cannot be used until the FPGA fabric is configured.

The project also demonstrates how the spidev Linux driver can be leveraged to enable applications runnning in userspace to perform generic raw SPI transfers to SPI devices. This can be useful when the device to be controlled does not fit into a defined category of devices supported by the Linux kernel. Note the actual example shown here uses a QSPI flash memory as the SPI slave, for which a standard driver does exist.

The project also demonstrates how to use a GPIO to control the SPI CS signal. This is because the SPI controller alone does not allow full control of the CS signal. In this project, a soft IP instantiated in the FPGA fabric is used, but the same concept applies when the dedicated HPS pins are used.

Deliverables

There are no included binaries, source code or patches. Thee included instructions should be sufficient to allow reproducing the project.

Prerequisites

You will need the following items:

• Linux host PC (Ubuntu 16.04LTS was used for developing this project, but other versions may work too)
• Internet access (for downloading various items)
• Quartus Prime Pro v19.1 - for compiling the hardware design
• SoC EDS Pro v19.1 - for the S10 SoC GHRD
• Stratix 10 SoC Development Board with
  • SDMMC HPS Daughtercard
  • SDM QSPI Bootcard - for configuring FPGA and HPS FSBL
  • Additional SDM QSPI Bootcard - conencted to FPGA, to be accessed over SPI

References:

• Stratix 10 SoC HPS Technical Reference Manual
• Spidev Kernel Documentation
• Accessing SPI Devices in Linux

Building the Project

Build Flow Overview

Setup Environment

Create a top folder for this example, as the rest of the commands assume this location:

mkdir ~/s10_spim_fpga

All the instructions for building the example are to be run from an Embedded Command Shell, which is started by running the following command:

~/intelFPGA_pro/19.1/embedded/embedded_command_shell.sh

Compilation of the software relies on downloading the build toolchain and adding it to the PATH variable:

cd ~/s10_spim_fpga
wget https://releases.linaro.org/components/toolchain/binaries/7.2-2017.11/aarch64-linux-gnu/gcc-linaro-7.2.1-2017.11-x86_64_aarch64-linux-gnu.tar.xz
tar xf gcc-linaro-7.2.1-2017.11-x86_64_aarch64-linux-gnu.tar.xz
export PATH=`pwd`/gcc-linaro-7.2.1-2017.11-x86_64_aarch64-linux-gnu/bin/:$PATH

Build Hardware Design

This section presents how to take the GHRD and update it so that it routes the SPIM0 signals to FPGA fabric, and the connects that to the FPGA pins on the FPGA flash connector.

1. Get the GHRD from SoC EDS and clean it:

cd ~/s10_spim_fpga 
mkdir s10_soc_devkit_ghrd_spim0fpga
cd s10_soc_devkit_ghrd_spim0fpga
tar xf $SOCEDS_DEST_ROOT/examples/hardware/s10_soc_devkit_ghrd/tgz/*.tar.gz
make clean
rm -rf qdb stamp synth_dumps tmp-clearbox *.csv software/ output_files/
find  *.qsys -maxdepth 0 | cut -f1 -d"." | xargs -I{} rm -rf {}
find  *.qsys -maxdepth 0 | cut -f1 -d"." | xargs -I{} find ip/{}/ -type f -not -name "*.ip" | xargs rm
find . -type d -empty -delete

2. Open qsys_top.qsys in Platform Designer and perform the following:

• Configure SPIM0 to go to FPGA fabric:
  • Click on the s10_hps component and go to Pin Mux and Peripherals > Advanced > Advanced FPGA placement and select the Route to FPGA box for SPIM0 to Yes, then click on Apply Selections.
  • Export the s10_hps.spim0 conduit by double clicking in the Export column, it will create the s10_hps_spim0 conduit.
  • Export the s10_hp.spim0_sclk_out conduit by double-clicking it in the Export column, it will create the s10_hps_spim0_sclk_out conduit.
• Add a new GPIO soft IP to use as SPI chip select, since the controller does not allow us to reliably do that in all situations:
  • Add a new component of type PIO (Parallel I/O) Intel FPGA IP, name it spi_cs_pio and configure it as follows:
    • Width: 1
    • Direction: bidir (we only need output, but I don’t think the Linux driver supports that, although it may).
    • Enable individual bit setting/clearing: yes
    • Output Port Reset Value: 0x0000000000000001
• Change the base address of spi_cs_pio.s1 to 0x0001_0000 to avoid conflicts with other IPs
• Connect the spi_cs_pio as follows:
  • clk: to clk_100.out_clk
  • reset: to rst_in.out_reset
  • s1: to s10_hps.h2f_lw_axi_master
  • Export spi_cs_pio.external connection by double clicking it, it will create the conduit spi_cs_pio.spi_cs_pio_external_connection_export.
• The System Messages window will display the message “Component Instantiation Warning: qsys_top.pio_0: System Information doesn't match requirements of IP. Double-click to open System Info tab.”. Right-click it and select Sync This Module’s System Infos and the warning will disappear.
• Go to Generate > Show Instantiation Template, and save in a file the template, so you have the new signal names for qsys_top.
• Click on Generate button to generate the system.

3. In ghrd_s10_top.v:

• Add the top level signals connecting to SPI

module ghrd_s10_top (
output wire spi_clk,
output wire spi_cs,
output wire spi_mosi,
input  wire spi_miso,

• Hook up the relevant Qsys exported signals to the top level signals:

qsys_top soc_inst (
.s10_hps_spim0_sclk_out_clk            (spi_clk),
.spi_cs_pio_external_connection_export (spi_cs),
.s10_hps_spim0_mosi_o                  (spi_mosi),
.s10_hps_spim0_miso_i                  (spi_miso),
.s10_hps_spim0_ss_in_n                 (1'b1),

4. In ghrd_1sx280lu2f50e2vg.qsf connect the top level signals to the correct pins on the DevKit, and set them to 1.8V:

set_location_assignment PIN_BD28 -to spi_clk
set_location_assignment PIN_BF26 -to spi_cs
set_location_assignment PIN_BC28 -to spi_mosi
set_location_assignment PIN_BE27 -to spi_miso
set_instance_assignment -name IO_STANDARD "1.8 V" -to spi_clk -entity ghrd_s10_top
set_instance_assignment -name IO_STANDARD "1.8 V" -to spi_cs -entity ghrd_s10_top
set_instance_assignment -name IO_STANDARD "1.8 V" -to spi_mosi -entity ghrd_s10_top
set_instance_assignment -name IO_STANDARD "1.8 V" -to spi_miso -entity ghrd_s10_top

5.Compile the hardware design

Build U-Boot

Retrieve the U-Boot source code and compile it as shown below (note that there are no U-Boot changes required):

cd ~/s10_spim_fpga
rm -rf u-boot-socfpga
git clone https://github.com/altera-opensource/u-boot-socfpga
cd u-boot-socfpga
git checkout -t -b test_branch origin/socfpga_v2017.09
make clean && make mrproper
make socfpga_stratix10_defconfig
make -j 24
aarch64-linux-gnu-objcopy -I binary -O ihex \
    --change-addresses 0xffe00000 spl/u-boot-spl-dtb.bin spl/u-boot-spl.hex
cd ..

Create SDM Flash Programming File

Create JIC file (using smaller device to make smaller file, but it also works on the 2Gb part):

cd ~/s10_spim_fpga
quartus_pfg -c \
      s10_soc_devkit_ghrd_spim0fpga/output_files/ghrd_1sx280lu2f50e2vg.sof \
      s10_image_spim0fpga.jic \
      -o device=MT25QU128 \
      -o flash_loader=1SX280LU3S2 \
      -o hps_path=u-boot-socfpga/spl/u-boot-spl.hex \
      -o mode=ASX4

Build Linux

1. Clone the Linux git tree and get the LTSI branch:

cd ~/s10_spim_fpga
rm -rf linux-socfpga
git clone https://github.com/altera-opensource/linux-socfpga
cd linux-socfpga
git checkout -t -b test_branch/socfpga-4.14.73-ltsi

2. Change the kernel configuration by editing arch/arm64/configs/defconfig as follows:

CONFIG_SPI_SPIDEV=y
CONFIG_GPIO_ALTERA=y
CONFIG_SPI_DESIGNWARE=y
CONFIG_SPI_DW_MMIO=y

3. Edit the device tree file arch/arm64/boot/dts/altera/socfpga_stratix10_socdk.dts as follows:

a) Add the FPGA clock that is used by FPGA fabric:

clk_100: clk_100 {
   compatible = "fixed-clock";
   clock-frequency = <100000000>;	
   clock-output-names = "clk_100-out_clk";
};

b) Add the PIO module which controls the SPI CS signal:

spi_cs_pio: gpio@0xf9010000 {
   compatible = "altr,pio-19.1", "altr,pio-1.0";
   reg = <0xf9010000 0x00000020>;
   clocks = <&clk_100>;
   altr,gpio-bank-width = <1>;	
   resetvalue = <1>;
   #gpio-cells = <2>;
   gpio-controller;
   status = "okay";
};

c) Enable SPIM0, make it use the soft IP PIO as chip select, and enable it to be used by the spidev driver:

&spi0 {
   num-cs = <1>;
   cs-gpios = <&spi_cs_pio 0 0>;
   status = "okay";
   spidev@0 {
      compatible = "custom,spidev";
      reg = <0x0>;
      spi-max-frequency = <0x5F5E10>;
      enable-dma = <0x1>;
   };
};

4. Edit the spidev driver source file drivers/spi/spidev.c for the "compatible" property to match the device tree entry we made:

 	{ .compatible = "lineartechnology,ltc2488" },
 	{ .compatible = "ge,achc" },
 	{ .compatible = "semtech,sx1301" },
	{ .compatible = "custom,spidev" },
 	{},

5. Build Linux kernel and device trees:

make clean && make mrproper
make defconfig
make -j 12 Image dtbs
cd ..

Build Rootfs

There is nothing special about the rootfs. You can use your own or build one as shown below:

cd ~/s10_spim_fpga
sudo rm -rf angstrom
mkdir angstrom && cd angstrom
wget http://commondatastorage.googleapis.com/git-repo-downloads/repo
chmod 777 repo
export PATH=`pwd`:$PATH
repo init -u git://github.com/Angstrom-distribution/angstrom-manifest \
-b angstrom-v2018.06-sumo
repo sync
MACHINE=stratix10 . ./setup-environment
sed -i '/meta-atmel/d' conf/bblayers.conf
sed -i '/meta-optee/d' conf/bblayers.conf
sed -i '/meta-freescale/d' conf/bblayers.conf
sed -i '/meta-mono/d' conf/bblayers.conf
sed -i 's/IMAGE_FSTYPES.*/IMAGE_FSTYPES = "tar.gz"/g' conf/local.conf
echo "DISTRO_FEATURES_remove = \" wayland alsa \"" >> conf/local.conf
export KERNEL_PROVIDER=linux-altera-ltsi
export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE KERNEL_PROVIDER"
bitbake core-image-minimal-mtdutils

Build spidev Test Program

The test application is very simple, it creates a single SPI transfer composed of two buffers:

• One 1-byte TX buffer containing the flash Read ID command
• One 6-byte RX buffer containing the response from the flash to the Read ID command

1. Go to https://www.emcraft.com/stm32f429discovery/accessing-spi-devices-in-linux and copy-paste the simple demo application that shows how to read the Flash ID from an SPI Flash device from the bottom of the page, as spidev_flash_test.c.

2. Compile the above C source code file:

cd ~/s10_spim_fpga
${CROSS_COMPILE}gcc -static spidev_flash_test.c -o spidev_flash_test

Create SD Card Image

This sections shows how to create an SD card image with all the items necessary for booting Linux and demonstrating the spidev usage:

• U-Boot Image
• Linux Device Tree
• Linux Kernel
• Linux Rootfs, including the test program

The commands for creating the SD card are:

cd ~/s10_spim_fpga
sudo rm -rf sd_card && mkdir sd_card && cd sd_card
# get the sd card script and make it writable
wget https://releases.rocketboards.org/2018.10/gsrd/tools/make_sdimage.py
chmod +x make_sdimage.py
# copy all the required components to sd_card folder
cp ../u-boot-socfpga/u-boot-dtb.img .
cp ../linux-socfpga/arch/arm64/boot/Image .
cp ../linux-socfpga/arch/arm64/boot/dts/altera/socfpga_stratix10_socdk.dtb .
# create rootfs
mkdir rootfs && cd rootfs
sudo tar xf ../../angstrom/deploy/glibc/images/stratix10/core-image-minimal-mtdutils-stratix10.tar.gz
# remove modules compiled as part of Yocto build
sudo rm -rf lib/modules/*
sudo cp ../../spidev_flash_test home/root
cd ..
# create SD card image
sudo ./make_sdimage.py -f \
-P rootfs/*,num=2,format=ext3,size=300M \
-P u-boot-dtb.img,Image,socfpga_stratix10_socdk.dtb,num=1,format=vfat,size=100M \
-s 512M \
-n sd_card.img

Writing Binaries to Flash

Write SDM Flash Image

1. Install the QSPI SDM bootcard on the S10 SoC Development Kit and configure the S10 SoC Development Kit as follows:

• SW1: 1:OFF, rest:ON
• SW2: 1:ON 2:ON 3: ON 4: OFF
• SW3: all OFF
• SW4: 1:ON 2:OFF 3:OFF 4:ON

2. Powe up the board

3. Run programmer to write the flash image:

cd ~/s10_spim_fpga/
quartus_pgm  -c 1 -m jtag -o "pvi;./initial_image.jic"

Write SD Card Image

1. Determine the device associated with the SD card on the host by running the following command before and after inserting the card in the reader:

cat /proc/partitions 

Let's assume it is /dev/sdx.

2. Use dd utility to write the SD image to the SD card:

cd ~/s10_spim_fpga/sd_card
sudo dd if=sd_card.img of=/dev/sdx bs=1M

Warning: be very careful to only write to the SD card partition. The dd command is extremely powerful, and you can destroy your Linux installation and all your data with it, if you are not careful.

3. Use sync utility to flush the changes to the SD card:

sudo sync

Running the Project

1. Configure the S10 SoC Development Kit to configure FPGA and load FSBL from QSPI:

• SW1: 1:OFF, rest:ON
• SW2: 1:ON 2:OFF 3:OFF 4: OFF
• SW3: all OFF
• SW4: 1:ON 2:OFF 3:OFF 4:ON

2. Connect to board USB serial port with a console program like minicom, using 115200-8-N-1 settings.

3. Power up the board

4. Stop at U-Boot prompt by pressing any key during U-Boot countdown

5. Run the “bridge enable” U-Boot command to open the bridges

6. Run “run bootcmd” U-Boot command to boot Linux

7. Enter userame 'root' when asked by Linux. No password will be requested.

8. Test spidev program by using it to read the flash id from the QSPI bootcard connected to FPGA flash slot:

• For a Macronix MX25U128 part:

root@stratix10:~# ./spidev_flash_test /dev/spidev0.0
response(7): c2 25 38 c2 25 38

• For a Micron MT25QU01G part:

root@stratix10:~# ./spidev_flash_test /dev/spidev0.0
response(7): 20 bb 21 10 44 00

• For the standard Micron MT25QU02G part:

root@stratix10:~# ./spidev_flash_test /dev/spidev0.0
response(7): 20 bb 22 10 44 00