2016-01-17: First release of IceTime timing analysis. Video: https://youtu.be/IG5CpFJRnOk
2015-12-27: Presentation of the IceStorm flow at 32C3 (Video on Youtube).
2015-07-19: Released support for 8k chips. Moved IceStorm source code to GitHub.
2015-05-27: We have a working fully Open Source flow with Yosys and Arachne-pnr! Video: http://youtu.be/yUiNlmvVOq8
2015-04-13: Complete rewrite of IceUnpack, added IcePack, some major documentation updates
2015-03-22: First public release and short YouTube video demonstrating our work: http://youtu.be/u1ZHcSNDQMM
Project IceStorm aims at reverse engineering and documenting the bitstream format of Lattice iCE40 FPGAs and providing simple tools for analyzing and creating bitstream files. The IceStorm flow (Yosys, Arachne-pnr, and IceStorm) is a fully open source Verilog-to-Bitstream flow for iCE40 FPGAs.
The focus of the project is on the iCE40 LP/HX 1K/4K/8K chips. (Most of the work was done on HX1K-TQ144 and HX8K-CT256 parts.)
It has a very minimalistic architecture with a very regular structure. There are not many different kinds of tiles or special function units. This makes it both ideal for reverse engineering and as a reference platform for general purpose FPGA tool development.
Also, with the Lattice iCEstick there is a cheap and easy to use development platform available, which makes the part interesting for all kinds of projects. (The iCEstick features an HX1K device. Lattice also sells an iCE40-HX8K Breakout Board featuring an HX8K chip.)
We are pretty confident that we have the 1K and 8K devices completely reverse engineered. For example, it seems we can create correct functional Verilog models for all bitstreams generated by Lattice iCEcube2 for the iCE40 HX1K-TQ144 and the iCE40 HX8K-CT256 using our icebox_vlog tool.
Here is a list of currently supported parts and the corresponding options for arachne-pnr (place and route) and icetime (timing analysis):
| Part | Package | Pin Spacing | I/Os | arachne-pnr opts | icetime opts |
|---|---|---|---|---|---|
| iCE40-LP1K-SWG16TR | 16-ball WLCSP (1.40 x 1.48 mm) | 0.35 mm | 10 | -d 1k -P swg16tr | -d lp1k |
| iCE40-LP1K-CM36 | 36-ball ucBGA (2.5 x 2.5 mm) | 0.40 mm | 25 | -d 1k -P cm36 | -d lp1k |
| iCE40-LP1K-CM49 | 49-ball ucBGA (3 x 3 mm) | 0.40 mm | 35 | -d 1k -P cm49 | -d lp1k |
| iCE40-LP1K-CM81 | 81-ball ucBGA (4 x 4 mm) | 0.40 mm | 63 | -d 1k -P cm81 | -d lp1k |
| iCE40-LP4K-CM81 | 81-ball ucBGA (4 x 4 mm) | 0.40 mm | 63 | -d 8k -P cm81:4k | -d lp8k |
| iCE40-LP8K-CM81 | 81-ball ucBGA (4 x 4 mm) | 0.40 mm | 63 | -d 8k -P cm81 | -d lp8k |
| iCE40-LP1K-CM121 | 121-ball ucBGA (5 x 5 mm) | 0.40 mm | 95 | -d 1k -P cm121 | -d lp1k |
| iCE40-LP4K-CM121 | 121-ball ucBGA (5 x 5 mm) | 0.40 mm | 93 | -d 8k -P cm121:4k | -d lp8k |
| iCE40-LP8K-CM121 | 121-ball ucBGA (5 x 5 mm) | 0.40 mm | 93 | -d 8k -P cm121 | -d lp8k |
| iCE40-LP4K-CM225 | 225-ball ucBGA (7 x 7 mm) | 0.40 mm | 167 | -d 8k -P cm225:4k | -d lp8k |
| iCE40-LP8K-CM225 | 225-ball ucBGA (7 x 7 mm) | 0.40 mm | 178 | -d 8k -P cm225 | -d lp8k |
| iCE40-HX8K-CM225 | 225-ball ucBGA (7 x 7 mm) | 0.40 mm | 178 | -d 8k -P cm225 | -d hx8k |
| iCE40-LP1K-QN84 | 84-pin QFNS (7 x 7 mm) | 0.50 mm | 67 | -d 1k -P qn84 | -d lp1k |
| iCE40-LP1K-CB81 | 81-ball csBGA (5 x 5 mm) | 0.50 mm | 62 | -d 1k -P cb81 | -d lp1k |
| iCE40-LP1K-CB121 | 121-ball csBGA (6 x 6 mm) | 0.50 mm | 92 | -d 1k -P cb121 | -d lp1k |
| iCE40-HX1K-CB132 | 132-ball csBGA (8 x 8 mm) | 0.50 mm | 95 | -d 1k -P cb132 | -d hx1k |
| iCE40-HX4K-CB132 | 132-ball csBGA (8 x 8 mm) | 0.50 mm | 95 | -d 8k -P cb132:4k | -d hx8k |
| iCE40-HX8K-CB132 | 132-ball csBGA (8 x 8 mm) | 0.50 mm | 95 | -d 8k -P cb132 | -d hx8k |
| iCE40-HX1K-VQ100 | 100-pin VQFP (14 x 14 mm) | 0.50 mm | 72 | -d 1k -P vq100 | -d hx1k |
| iCE40-HX1K-TQ144 | 144-pin TQFP (20 x 20 mm) | 0.50 mm | 96 | -d 1k -P tq144 | -d hx1k |
| iCE40-HX4K-TQ144 | 144-pin TQFP (20 x 20 mm) | 0.50 mm | 107 | -d 8k -P tq144:4k | -d hx8k |
| iCE40-HX8K-CT256 | 256-ball caBGA (14 x 14 mm) | 0.80 mm | 206 | -d 8k -P ct256 | -d hx8k |
Current work focuses on further improving our timing analysis flow.
Synthesis for iCE40 FPGAs can be done with Yosys. Place-and-route can be done with arachne-pnr. Here is an example script for implementing and programming the rot example from arachne-pnr (this example targets the iCEstick development board):
yosys -p "synth_ice40 -blif rot.blif" rot.v arachne-pnr -d 1k -p rot.pcf rot.blif -o rot.asc icepack rot.asc rot.bin iceprog rot.bin
A simple timing analysis report can be generated using the icetime utility:
icetime -tmd hx1k rot.asc
Installing prerequisites (this command is for Ubuntu 14.04):
sudo apt-get install build-essential clang bison flex libreadline-dev \
gawk tcl-dev libffi-dev git mercurial graphviz \
xdot pkg-config python python3 libftdi-dev
Installing the IceStorm Tools (icepack, icebox, iceprog, icetime, chip databases):
git clone https://github.com/cliffordwolf/icestorm.git icestorm cd icestorm make -j$(nproc) sudo make install
Installing Arachne-PNR (the place&route tool):
git clone https://github.com/cseed/arachne-pnr.git arachne-pnr cd arachne-pnr make -j$(nproc) sudo make install
Installing Yosys (Verilog synthesis):
git clone https://github.com/cliffordwolf/yosys.git yosys cd yosys make -j$(nproc) sudo make install
The Arachne-PNR build converts the IceStorm text chip databases into the arachne-pnr binary chip databases. Always rebuild Arachne-PNR after updating your IceStorm installation.
Notes for Archlinux: just install icestorm-git, arachne-pnr-git and yosys-git from the Arch User Repository (no need to follow the install instructions above).
Notes for OSX: Please follow the additional instructions for OSX to install on OSX.
Please file an issue on github if you have additional notes to share regarding the install procedures on the operating system of your choice.
The IceStorm Tools are a couple of small programs for working with iCE40 bitstream files and our ASCII representation of it. The complete Open Source iCE40 Flow consists of the IceStorm Tools, Arachne-PNR, and Yosys.
The iceunpack program converts an iCE40 .bin file into the IceStorm ASCII format that has blocks of 0 and 1 for the config bits for each tile in the chip. The icepack program converts such an ASCII file back to an iCE40 .bin file. All other IceStorm Tools operate on the ASCII file format, not the bitstream binaries.
The icetime program is an iCE40 timing analysis tool. It reads designs in IceStorm ASCII format and writes times timing netlists that can be used in external timing analysers. It also includes a simple topological timing analyser that can be used to create timing reports.
A python library and various tools for working with IceStorm ASCII files and accessing the device database. For example icebox_vlog converts our ASCII file dump of a bitstream into a Verilog file that implements an equivalent circuit.
A small driver program for the FTDI-based programmer used on the iCEstick and HX8K development boards.
A tool for packing multiple bitstream files into one iCE40 multiboot image file.
A small program for calculating iCE40 PLL configuration parameters.
The IceStorm Makefile builds and installs two files: chipdb-1k.txt and chipdb-8k.txt. This files contain all the relevant information for arachne-pnr to place&route a design and create an IceStorm ASCII file for the placed and routed design.
IcePack/IceUnpack, IceBox, IceProg, IceTime, and IcePLL are written by Clifford Wolf. IcePack/IceUnpack is based on a reference implementation provided by Mathias Lasser. IceMulti is written by Marcus Comstedt.
If you have a question regarding the IceStorm flow, use the yosys tag on stackoverflow to ask your question. If your question is a general question about Verilog HDL design, please consider using the verilog tag on stackoverflow instead.
For general discussions go to the Yosys Subreddit or #yosys on freenode IRC.
If you have a bug report please file an issue on github. (IceStorm Issue Tracker, Yosys Issue Tracker, Arachne-PNR Issue Tracker)
Recommended reading: Lattice iCE40 LP/HX Family Datasheet, Lattice iCE Technology Library (Especially the three pages on "Architecture Overview", "PLB Blocks", "Routing", and "Clock/Control Distribution Network" in the Lattice iCE40 LP/HX Family Datasheet. Read that first, then come back here.)
The FPGA fabric is divided into tiles. There are IO, RAM and LOGIC tiles.
The iceunpack program can be used to convert the bitstream into an ASCII file that has a block of 0 and 1 characters for each tile. For example:
.logic_tile 12 12 000000000000000000000000000000000000000000000000000000 000000000000000000000011010000000000000000000000000000 000000000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000000000000 000000000000001011000000000000000000000000000000000000 000000000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000000000000 000000000000000000000000001000001000010101010000000000 000000000000000000000000000101010000101010100000000000
This bits are referred to as By[x] in the documentation. For example, B0 is the first line, B0[0] the first bit in the first line, and B15[53] the last bit in the last line.
The icebox_explain program can be used to turn this block of config bits into a description of the cell configuration:
.logic_tile 12 12 LC_7 0101010110101010 0000 buffer local_g0_2 lutff_7/in_3 buffer local_g1_4 lutff_7/in_0 buffer sp12_h_r_18 local_g0_2 buffer sp12_h_r_20 local_g1_4
IceBox contains a database of the wires and configuration bits that can be found in iCE40 tiles. This database can be accessed via the IceBox Python API. But IceBox is a large hack. So it is recommended to only use the IceBox API to export this database into a format that fits the target application. See icebox_chipdb for an example program that does that.
The recommended approach for learning how to use this documentation is to synthesize very simple circuits using Yosys and Arachne-pnr, run the icestorm tool icebox_explain on the resulting bitstream files, and analyze the results using the HTML export of the database mentioned above. icebox_vlog can be used to convert the bitstream to Verilog. The output file of this tool will also outline the signal paths in comments added to the generated Verilog code.
For example, consider the following Verilog and PCF files:
// example.v module top (input a, b, output y); assign y = a & b; endmodule # example.pcf set_io a 1 set_io b 10 set_io y 11
And run them through Yosys, Arachne-PNR and IcePack:
$ yosys -p 'synth_ice40 -top top -blif example.blif' example.v $ arachne-pnr -d 1k -o example.asc -p example.pcf example.blif $ icepack example.asc example.bin
We would get something like the following icebox_explain output:
$ icebox_explain example.asc Reading file 'example.asc'.. Fabric size (without IO tiles): 12 x 16 .io_tile 0 10 IOB_1 PINTYPE_0 IOB_1 PINTYPE_3 IOB_1 PINTYPE_4 IoCtrl IE_0 IoCtrl IE_1 IoCtrl REN_0 buffer local_g0_5 io_1/D_OUT_0 buffer logic_op_tnr_5 local_g0_5 .io_tile 0 14 IOB_1 PINTYPE_0 IoCtrl IE_1 IoCtrl REN_0 buffer io_1/D_IN_0 span4_vert_b_6 .io_tile 0 11 IOB_0 PINTYPE_0 IoCtrl IE_0 IoCtrl REN_1 routing span4_vert_t_14 span4_horz_13 .logic_tile 1 11 LC_5 0001000000000000 0000 buffer local_g0_0 lutff_5/in_1 buffer local_g3_0 lutff_5/in_0 buffer neigh_op_lft_0 local_g0_0 buffer sp4_h_r_24 local_g3_0
And something like the following icebox_vlog output:
$ icebox_vlog -p example.pcf example.asc // Reading file 'example.asc'.. module chip (output y, input b, input a); wire y; // io_0_10_1 // (0, 10, 'io_1/D_OUT_0') // (0, 10, 'io_1/PAD') // (0, 10, 'local_g0_5') // (0, 10, 'logic_op_tnr_5') // (0, 11, 'logic_op_rgt_5') // (0, 12, 'logic_op_bnr_5') // (1, 10, 'neigh_op_top_5') // (1, 11, 'lutff_5/out') // (1, 12, 'neigh_op_bot_5') // (2, 10, 'neigh_op_tnl_5') // (2, 11, 'neigh_op_lft_5') // (2, 12, 'neigh_op_bnl_5') wire b; // io_0_11_0 // (0, 11, 'io_0/D_IN_0') // (0, 11, 'io_0/PAD') // (1, 10, 'neigh_op_tnl_0') // (1, 10, 'neigh_op_tnl_4') // (1, 11, 'local_g0_0') // (1, 11, 'lutff_5/in_1') // (1, 11, 'neigh_op_lft_0') // (1, 11, 'neigh_op_lft_4') // (1, 12, 'neigh_op_bnl_0') // (1, 12, 'neigh_op_bnl_4') wire a; // io_0_14_1 // (0, 11, 'span4_horz_13') // (0, 11, 'span4_vert_t_14') // (0, 12, 'span4_vert_b_14') // (0, 13, 'span4_vert_b_10') // (0, 14, 'io_1/D_IN_0') // (0, 14, 'io_1/PAD') // (0, 14, 'span4_vert_b_6') // (0, 15, 'span4_vert_b_2') // (1, 11, 'local_g3_0') // (1, 11, 'lutff_5/in_0') // (1, 11, 'sp4_h_r_24') // (1, 13, 'neigh_op_tnl_2') // (1, 13, 'neigh_op_tnl_6') // (1, 14, 'neigh_op_lft_2') // (1, 14, 'neigh_op_lft_6') // (1, 15, 'neigh_op_bnl_2') // (1, 15, 'neigh_op_bnl_6') // (2, 11, 'sp4_h_r_37') // (3, 11, 'sp4_h_l_37') assign y = /* LUT 1 11 5 */ b ? a : 0; endmodule
Links to related projects. Contact me at clifford@clifford.at if you have an interesting and relevant link.
In papers and reports, please refer to Project IceStorm as follows: Clifford Wolf, Mathias Lasser. Project IceStorm. http://www.clifford.at/icestorm/, e.g. using the following BibTeX code:
@MISC{IceStorm,
author = {Clifford Wolf and Mathias Lasser},
title = {Project IceStorm},
howpublished = "\url{http://www.clifford.at/icestorm/}"
}
Documentation mostly by Clifford Wolf <clifford@clifford.at> in 2015. Based on research by Mathias Lasser and Clifford Wolf.
Buy an iCEstick or iCE40-HX8K Breakout Board from Lattice and see what you can do with the tools and information provided here.