Author: m s

Posted on by

ECP5 and SPI data overlay

As described in a previous blog post on playing with the ECP5 under Linux, I’ve ported a IoT and networking proven concept to the Versa ECP5G developer kit from Lattice. As we don’t want to use up the entire RAM for program code or data that is rarely used, another attempt was made on this platform to recreate the SPI cache trick implemented on Xilinx Spartan[3,6] hardware (Virtual ROM on small FPGAs).

The first blind run without reading the docs threw me an error: the SPI MCLK dedicated pin can not be used in “user mode”, i.e. after the FPGA has booted. Well, not as user pin, that is. However, the ECP5 has a specific primitive called USRMCLK which obviously allows to mux in a user defined clock to the MCLK pin. However, this requires you to turn off the MASTER_SPI_PORT option in the SYSCONFIG line of your preference *.lpf:

SYSCONFIG SLAVE_SPI_PORT=DISABLE CONFIG_MODE=JTAG CONFIG_SECURE=OFF TRANSFR=OFF MASTER_SPI_PORT=DISABLE SLAVE_PARALLEL_PORT=DISABLE MCCLK_FREQ=38.8 BACKGROUND_RECONFIG=OFF ;

The other SPI pins (MISO/MOSI/CS) again are accessed as normal user pins specified in the LPF. The SPI clock from the custom SPI IP core (there’s no hard IP as in the MachXO* platforms) is silently routed through the USRMCLK primitive to the MCLK pin after the boot process has finished. The USRMCLK also requires a tristate input signal (‘1’ = SPI clock not active). If you are tempted to use this as a clock enable: Don’t. Just feed the gated SPI clock to the usrmclki pin of the USRMCLK primitive and use the /CS signal of the SPI core for the usrmclkts pin.

The disadvantage of this solution: When MASTER_SPI_PORT is disabled, background programming of the SPI flash through the Diamond Programmer will no longer work. Every time you update, you will have to load another bit file with enabled MSPI before you can update the flash. Or alternatively, mess with the boot mode so that you have a default configuration allowing background programming.

On the other hand, we can now update the flash “in system” using a simple UART boot loader so we don’t have to wait for the somewhat painfully slow Programmer to finish.

Program layout

Using the linker script has already been described in (Virtual ROM on small FPGAs). Using this technique again, we relocate all seldom used programm code such as initialization code into the external program memory. We then end up with the boot ROM code in a pure HDL file (RAM initialization bit vectors) and a binary image containing the program/data overlay code. This image is created by a simple objcopy call from the Firmware Makefile:

zpu-elf-objcopy \
        -j .ext.text \
        -j .ext.rodata \
        -O binary main.elf flashdata.bin

This is assembled using the Deployment Tool of the Diamond Programmer, found in the Utilities menu. This tool creates an intel hex file (*.mcs) from the BIT file and an attached flashdata.bin that you can select under the “User Data Files” tap in the Advanced SPI flash creation wizard. Finally, this MCS file can be burned into the SPI flash using the boot loader command:

# bl                                                                            
> Waiting for data..

Then simply upload the mcs file to the target inside your terminal program. Then you can hit the PROG button (not the global reset) to load the new image. Note that there are no safety checks at this moment, an illegal image will not boot and you will have to use the Programmer again.

SPI flash filesystems

A nice way to store files (such as default settings) on the target is by using the OpenSource spiffs tools. It may not fit into the standard configuration though, the library itself is roughly 36k in size. You could try to put parts of it into “overlay”, but it is probably safer to keep it in L1 memory and increase that by another power of two.

This is the repo we use:

https://github.com/pellepl/spiffs.git

 

Posted on by — 2 Comments

ECP5G Versa board under Linux

The ECP5 platform has caught quite some attention a while ago, being on the rather high end with respect to GigaBit LVDS communication of all sorts. It’s the successor of the ECP3 which has been performing well with HDMI applications in the past.

Lattice Semiconductor had launched a Promo action for this Versa ECP5G board. With great assistance from Future Electronics Switzerland I was able to get hold of a devkit.

Running the Lattice Diamond toolchain on a Linux environment has so far been straightforward, with minor quirks on the GUI side. Let me revisit the important items to get up and running. If you happen to have a Linux OS installed that does not match the Lattice Semi recommendations for a development system, you might want to look at the Docker approach on how to set up the environment.

Programmer preparation

Porting a very simple CPU with UART interface to the platform, the final step is flashing things down into the board using the Lattice Diamond Programmer. Usually, when not having installed any udev rules, these are the steps you have to go through with root powers, in order to get the USB FTDI programmer interface recognized:

Bus 001 Device 013: ID 0403:6010 Future Technology Devices International, Ltd FT2232C Dual USB-UART/FIFO IC

According to this device enumeration, you give access to the device:

chmod a+rw /dev/bus/usb/001/013

and unbind the first ttyUSB0 device from the ftdi_sio driver – unfortunately, the Lattice driver is not able to unbind from within.

echo -n $TTY_ID > /sys/bus/usb/drivers/ftdi_sio/unbind

Replace $TTY_ID by the tty device entry in /sys/bus/usb/drivers/ftdi_sio/ that typically is of the form “1-3.2:1.0” (the trailing 0 stands for port A where the JTAG is at). If you have plugged in more than one FTDI adapter with UART capabilities, you will see several and need to figure out which is which.

Now you can download code into the programmer.

To automatize the process, you could also use the script below:

#/bin/bash

allow_io=`lsusb | sed -n 's/^Bus \([0-9]*\) Device \([0-9]*\): ID 0403:6010 .*/\1\/\2/p'`

unbind_tty=`ls /sys/bus/usb/drivers/ftdi_sio/ | sed -n 's/\(.*\:1\.0\).*/\1/p'`

sudo chmod a+rw \/dev\/bus\/usb\/$allow_io
sudo sh -c "echo $unbind_tty > /sys/bus/usb/drivers/ftdi_sio/unbind"

SPI flash download

When downloading your design into the SPI flash, make sure you have MASTER_SPI_PORT=ENABLED set in your *.lpf file. Otherwise the programmer will fail with an error report on CHECK_ID:

ERROR - Verification Error...when Processing function: 'CHECK_ID'

Then you’ll have to use the fast download (into SRAM) with an enabled Master SPI in order to be able to flash again.

Design issues

When starting to port our SoC design to this board, quite a few issues came up:

  • Don’t bother developing with Diamond v3.7. Some very obscure behaviour with wrong I/O mapping cost quite some headache. Seems to be solved in v3.8
  • v3.8 however is somewhat misleading with respect to output and return states from the Synopsys Synthesis engine ‘Synplify’. Make sure to check your design thoroughly, if Synplify throws an error, Diamond sometimes would not recognize that and map/PAR an old design netlist.
  • Weird random behaviour can occur under Linux with Diamond during PAR, like error messages with respect to path names. This seems to happen especially with long names and underscores. The behaviour has been around in many previous versions of Diamond, Tech Support has refused to accept this as a bug so far. The workaround is to call PAR using the command line (TCL) or use the Run Manager.
    Addendum: It seems that this bug is fixed in v3.9, but there is no release note about it.

 

Talking through the UART

In theory, you should be able to talk to your design through the UART (if your design supports it) by firing up minicom:

minicom -o -D /dev/ttyUSB1

Now here comes the catch: The default EEPROM from my Versa 5G board did not have a correct descriptor, however it came with the default VID:PID from FTDI, so the ftdi_sio driver would recognize it, but in fact not communicate, neither report an error.

So, in order to properly use this board, you may have to erase the EEPROM of the FTDI adapter on the Versa kit using FTDIs Mprog tool or alike. You might want to save the previous EEPROM content for reference, however it does not seem needed, the Programmer recognizes the Board just fine.

Finally, after downloading our SoC setup into the board, it is talking:

Booting, HW rev: 04 -- Running at 50 MHZ

------------- test shell -------------
-- ZpuSoC for Versa ECP5 --
-- (c) 2017 www.section5.ch --
-- type 'h' for help --
#

Simulation issues

When trying to fully simulate the SoC setup with PLL primitives and some instanced ip cores created by the Clarity module (obviously that’s the IPExpress descendant for ECP5), it turns out that some of the simulation primitives for the VHDL side are missing.

Some of them could be converted using the VHDL conversion trick from Icarus Verilog by the following Makefile rule:

%.vhdl: %.v
    iverilog -tvhdl -o $@ -pdepth=1 $<

However, some of the needed components might not convert without additional tweaking. Hopefully, Lattice Semi will come out with updated VHDL libraries.

IPcore simulation under GHDL

When generating IP cores that depend on library items and running them through GHDL, you might see this error message:

warning: component instance "scuba_vlo_inst" is not bound

However, if you have prepared your FPGA primitive components library, like ecp5um-obj93.cf right, the primitive simulation models should be in there (search for ‘vlo’ in the *.cf file if in doubt).

The reason why this is happening is that there could be component prototype declarations in the IP core file that shouldn’t be there in order to reference to the components from the library. So: Just remove the “component” declaration sections and all should link fine. The drawback of this is, that you need two IP core versions, one for simulation and one for synthesis. If you have a better solution, let me know.

Next steps

Now, the fancy stuff on this board to be evaluated is:

  • DDR3 memory
  • Two GigE capable interfaces

Also, the ECP5 on this board has enough resources to run several ZPUng cores simultaneously. For safety reasons, we wouldn’t want the IoT crap run in the same environment as our controlling main loop.

Therefore, a second processor (Core B) is instanced for running the Ethernet Stack (lwip) only, while maintaining a simple DMA channel to the controller Core A for communication. If core B is compromised, Core A will still maintain its “hardened” control loop and not go haywire.

Implementing DDR3 is tricky. Therefore you might want to use the DDR3 IP core supplied by Lattice. On the demo kit, it will work for a few hours and then pull the global reset.

Networking

Of course, I was very curious about the Ethernet ports on this board. It’s armed with two GigE capable Marvell Phys whose data sheets are a little hard to get hold of, but one might also look at various source code around the web or just check the reference design from Lattice. The reference design uses lwip, since I only need and want UDP, I ported a zerocopy-capable UDP stack I developed for the Blackfin EMAC to the ZPUng SoC (“cranach”), which is equipped with some DMA capable scratch pad memory for a proper packet queue.

After all, the FPGA is now able to speak netpp, so I can turn on an LED for example:

> netpp UDP:192.168.05:2016 LED.Yellow 1

Resource usage

You might want to know how much logic and RAM is consumed by this solution.

Design Summary
   Number of registers:   2770 out of 44457 (6%)
      PFU registers:         2767 out of 43848 (6%)
      PIO registers:            3 out of   609 (0%)
   Number of SLICEs:      2963 out of 21924 (14%)
      SLICEs as Logic/ROM:   2891 out of 21924 (13%)
      SLICEs as RAM:           72 out of 16443 (0%)
      SLICEs as Carry:        309 out of 21924 (1%)
   Number of LUT4s:        4154 out of 43848 (9%)
   Number of block RAMs:  28 out of 108 (26%)
   Number of DCS:  1 out of 2 (50%)
   Number of PLLs:  1 out of 4 (25%)

As for the actual program code, containing:

  • UDP stack supporting ARP, ICMP ping
  • Minimal shell (UART)
  • System I/O drivers (UART, Timer, MAC, PWM)
  • netpp minimal server with some LED handling

This is what’s effectively downloaded into the target:

(gdb) init
Loading section .fixed_vectors, size 0x400 lma 0x0
Loading section .l1.text, size 0x4af5 lma 0x400
Loading section .rodata, size 0x168 lma 0x4ef8
Loading section .rodata.str1.4, size 0xf60 lma 0x5060
Loading section .data, size 0x2c0 lma 0x5fc0
Start address 0x0, load size 25213

There’s a significant amount of string data for debugging in the .rodata.str1.4 section due to debugging info, plus some netpp descriptors. These again could be ‘overlayed’ to the SPI flash, as they are not too frequently accessed. To be investigated next…

Posted on by — 14 Comments

Dockerized FPGA toolchains

For a while, LXC (linux container) technology might have been known for the better chroot. Docker takes this approach even further by letting you mess with changes and undo them easily. You can just install foreign binaries and play with dependencies without compromising your desktop host’s runtime libraries. This article describes how to easily put commercial FPGA toolchains into a docker environment and carry them around on an external hard disk for quick installation on a new developer machine.

Lattice Diamond

The Lattice Diamond toolchain comes as RPM package and is recommended to be run under a Redhat OS. It is possible to convert to a DEB and install and run it on a Debian system likewise, but we try basing it on a minimal RPM compatible environment as an existing CentOS container.

This short howto describes the necessary steps for Diamond v3.10 (older versions work likewise):

First create a file called Dockerfile, like:

FROM centos

RUN yum update ; \
	yum install -y freetype libSM libXrender fontconfig libXext libXt \
		tcl tcsh perl libXft xorg-x11-fonts-Type1 net-tools \
		libXScrnSaver-1.2.2 \
		libusb-0.1.4 usbutils


RUN adduser -u 1000 -g 100 diamond; echo ". env-setup.sh" >> /home/diamond/.bashrc

COPY env-setup.sh /home/diamond

ENTRYPOINT ["/bin/bash"]

You could automate things more by copying the RPM into the docker container, but that would just take useless space in the image (and stripping this back down would take extra action). Therefore we mount the directory where the RPM was downloaded to into the container. Unfortunately, there is no clean way to pull it from an official source the wget way.

You may have to sort out permissions first (by adding yourself to the ‘docker’ group) or prepend ‘sudo’ to each docker call.

The env-setup.sh is a small setup script needed to initialize the environment:

DIAMOND_DIR=/usr/local/diamond/3.10_x64

export DISPLAY=:0.0
bindir=$DIAMOND_DIR/bin/lin64

export QT_GRAPHICSSYSTEM=native

source $bindir/diamond_env

export LM_LICENSE_FILE=$HOME/license.dat

Building the container

  1. Change UID and GID for adduser command in the Dockerfile, if necessary
  2. Run 
    docker build -t diamond .
  3. Then you can start the docker container using the following command. Note you have to replace $ETHADDR by the ethernet MAC address you have registered your license.dat to. Also, make $PATH_TO_RPM_INSTALLDIR point to the directory where the downloaded RPM resides. 
    docker run -ti -e DISPLAY=:0 \
--mac-address=$ETHADDR \
--privileged --ipc host \
-v $PATH_TO_RPM_INSTALLDIR:/mnt \
-v /dev/bus/usb/:/dev/bus/usb/ \
-v /tmp/.X11-unix/:/tmp/.X11-unix diamond:latest
  4. Then install diamond by 
    rpm -i /mnt/diamond_3_10-base_x64-111-2-x86_64-linux.rpm
  5. You still need to copy your license.dat into your /home/diamond/ directory within the docker container. If it’s supposed to be elsewhere, edit the LM_LICENSE_FILE environment variable in env-setup.sh.
  6. Then you should be able to start the diamond GUI as user ‘diamond’: 
    su -l diamond
diamond
  7. Finally, if you are happy with your changes, you might want to commit everything to a new image: 
    docker commit -m "Diamond install" $HASH_OF_YOUR_CONTAINER diamond:v3.10

A few notes

The -v option takes care about sharing your X11 sockets with the docker sandbox. Note that there also some options inside the env-setup.sh to make QT work in this limited environment. Don’t try to run Diamond as root, as the X11 forwarding will not be allowed.

Lattice iCEcube2

The iCEcube2 2017.0.8 release includes a mix of 32 and 64 bit binaries, therefore requires installation of the i686 variants of some libraries. The minimal Dockerfile would here look as follows:

FROM centos

RUN yum update ; \
    yum install -y libXext libpng libSM libXi libXrender libXrandr \
        libXfixes libXcursor libXinerama freetype fontconfig

# 32 bit support:
RUN yum install -y glibc.i686 glib2.i686 \
    zlib.i686 libXext.i686 libpng12.i686 \
    libSM.i686 libXrender.i686 libXfixes.i686 libXrandr.i686 \
    libXcursor.i686 freetype.i686 fontconfig.i686 

RUN adduser -u 1000 -g 100 icecube2

ENTRYPOINT ["/bin/bash"]

Run the iCEcube2 installer binary obtained from latticesemi.com as user icecube2 and select the license file you have registered via the /mnt directory from your host OS.

Xilinx ISE

The same procedure works  for the ISE 14.7 toolchain. The Dockerfile in this case is almost similar, although includes a few X11 extras.

FROM centos

RUN yum update ; \
    yum install -y freetype libSM libXrender fontconfig libXext \
        tcl xorg-x11-fonts-Type1 net-tools libXScrnSaver-1.2.2 \
        libXi libXrandr \
        libusb-0.1.4 usbutils

RUN adduser -u 1000 -g 100 ise; echo ". env-setup.sh" >> /home/ise/.bashrc

COPY env-setup.sh /home/ise

ENTRYPOINT ["/bin/bash"]

Downloading and unpacking ISE

Make sure you have downloaded the following files from the Xilinx website:

Xilinx_ISE_DS_14.7_1015_1-1.tar
Xilinx_ISE_DS_14.7_1015_1-2.zip.xz
Xilinx_ISE_DS_14.7_1015_1-3.zip.xz
Xilinx_ISE_DS_14.7_1015_1-4.zip.xz

Then untar the first one by

> tar xf Xilinx_ISE_DS_14.7_1015_1-1.tar

This directory path will have to be exported to docker under $PATH_TO_UNPACKED_XILINX_TAR below.

The env-setup.sh file:

#!/bin/bash

export DISPLAY=:0.0
XILINXDIR=/opt/Xilinx/14.7/ISE_DS

. $XILINXDIR/settings64.sh
alias ise=$XILINXDIR/ISE/bin/lin64/ise

Likewise, the docker container is run by something like:

docker run -ti -e DISPLAY=:0 \
--mac-address=$ETHADDR \
--privileged --ipc host \
-v $PATH_TO_UNPACKED_XILINX_TAR:/mnt \
-v /dev/bus/usb/:/dev/bus/usb/ \
-v /tmp/.X11-unix/:/tmp/.X11-unix ise:latest

Once you’re inside docker, install as root by running /mnt/xsetup. This may take a long time. Left to do:

  • Install a license file
  • Mess with the USB drivers for Impact. This is left open to the user. I am using xc3sprog from my host system.