John Beetem's IceStorm Notes

Project IceStorm, by Clifford Wolf and Mathias Lasser, is an amazing project that has reverse-engineered the Lattice iCE40 FPGA's bitstream so that it's finally possible to write open-source FPGA design tools for a real FPGA.  I've been playing with IceStorm and its companion tool arachne-pnr (place & route) over the last few days and it's been loads of fun with very few problems.  I'm going to add IceStorm as a synthesis target for my XXICC (21st Century Co-design) project.  That will give me a complete open-source FPGA design system, something I've been wanting for decades.

This 'blog is for collecting links and notes for IceStorm so that others can find them quickly and easily.  I will be adding to it as I learn more.  This content is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License so others can share it.

Here is the official Project IceStorm wiki: Project IceStorm

Here is my original IceStorm discussion here at element14: Project IceStorm: fully open-source FPGA tools for Lattice iCE40

IceStorm uses a Lattice iCEstick as a development board.  It's available for US$21 in the USA: Lattice Semiconductor: ICE40HX1K-STICK-EVN iCEstick Evaluation Kit.

Here are instructions for installing IceStorm and its companion tools: Projet IceStorm: le FPGA libéré! [the FPGA set free!].  The instructions are a combination of French and GNU/Linux.  The IceStorm steps are out of date, since IceStorm is now at GitHub.  Here are the specific steps for IceStorm:

1.  Install "libftdi-dev" so IceStorm can talk to iCEstick's FT2232H:

$ sudo apt-get install libftdi-dev

2.  You can install IceStorm anywhere, but the standard place is in "/opt".  You'll probably need to change permissions on "/opt" so you can write to it.

$ cd /opt/

3.  Clone IceStorm from GitHub:

$ git clone https://github.com/cliffordwolf/icestorm.git icestorm

4.  Make the IceStorm software.  Some of it is in C++11, so your GCC will need to support it (GCC 4.8.1 or later).  The "make" step builds textual chip databases using a Python program, which takes a while on a slow computer.

$ cd icestorm

$ make

$ sudo make install

That's it!  IceStorm is ready to go.

Here is a partial list of IceStorm programs.  Like many open-source projects, IceStorm does not have a lot of documentation.  The IceStorm wiki is your best starting point.  However, each program does have a way to print help.

icepack takes a FPGA configuration data in text form (usually from arachne-pnr) and packs it into a binary file for downloading.  Here is a typical icepack command:

$ icepack moebius.txt moebius.bin

To list icepack options, give the command "icepack -h".

iceprog downloads a bitstream to an iCE40 FPGA or to a serial flash.  Here is a typical iceprog command:

$ sudo iceprog moebius.bin

If you don't want to use sudo, you can add a "rules" file to "/etc/udev/rules.d": see udev rules file for FTDI FT2232D/H, FT232H, and Papilio DUO.

To list iceprog options, give the "iceprog" command with no arguments.  For an iCEstick, iceprog programs the serial flash and then resets the FPGA so that it programs itself from the serial flash.  You can't program the FPGA's internal SRAM directly because of the way the SPI interfaces are wired together.  It is possible to modify iCEstick to program SRAM directly, but you lose the serial flash chip.  The "iceprog" command with no arguments tells you how to do this.