Project IceStorm
================

| **2018-01-30:** Released support for iCE40 UltraPlus devices.
| **2017-03-13:** Released support for LP384 chips (in all package
  variants).
| **2016-02-07:** Support for all package variants of LP1K, LP4K, LP8K
  and HX1K, HX4K, and HX8K.
| **2016-01-17:** First release of IceTime timing analysis. Video:
  https://youtu.be/IG5CpFJRnOk
| **2015-12-27:**
  `Presentation <_static/slides.pdf>`__
  of the IceStorm flow at 32C3 (`Video on
  Youtube <https://www.youtube.com/watch?v=SOn0g3k0FlE>`__).
| **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 <https://github.com/YosysHQ/yosys>`__ and
  `Arachne-pnr <https://github.com/YosysHQ/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

What is Project IceStorm?
-------------------------

Project IceStorm aims at documenting the bitstream format of Lattice
iCE40 FPGAs and providing simple tools for analyzing and creating
bitstream files. The IceStorm flow
(`Yosys <https://github.com/YosysHQ/yosys>`__,
`Arachne-pnr <https://github.com/YosysHQ/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.) The iCE40
UltraPlus parts are also supported, including DSPs, oscillators, RGB and
SPRAM. iCE40 LM, Ultra and UltraLite parts are not yet supported.

Why the Lattice iCE40?
----------------------

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 creating bitstream documentations and as a
reference platform for general purpose FPGA tool development.

Also, with the `Lattice
iCEstick <http://www.latticesemi.com/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 <http://www.latticesemi.com/en/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx>`__
featuring an HX8K chip.)

What is the Status of the Project?
----------------------------------

We are pretty confident that we have the 1K and 8K devices completely
documented. 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     | I/Os | nextpnr | arac    | icetime |
|         |         | Spacing |      | opts    | hne-pnr | opts    |
|         |         |         |      |         | opts    |         |
+=========+=========+=========+======+=========+=========+=========+
| iCE4    | 16-ball | 0.35 mm | 10   | --lp1k  | -d 1k   | -d lp1k |
| 0-LP1K- | WLCSP   |         |      | --      | -P      |         |
| SWG16TR | (1.40 x |         |      | package | swg16tr |         |
|         | 1.48    |         |      | swg16tr |         |         |
|         | mm)     |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 30-ball | 0.40 mm | 21   | --up5k  | -d 5k   | -d up5k |
| E40-UP3 | WLCSP   |         |      | --      | -P      |         |
| K-UWG30 | (2.15 x |         |      | package | uwg30   |         |
|         | 2.55    |         |      | uwg30   |         |         |
|         | mm)     |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 30-ball | 0.40 mm | 21   | --up5k  | -d 5k   | -d up5k |
| E40-UP5 | WLCSP   |         |      | --      | -P      |         |
| K-UWG30 | (2.15 x |         |      | package | uwg30   |         |
|         | 2.55    |         |      | uwg30   |         |         |
|         | mm)     |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 36-ball | 0.40 mm | 25   | --lp384 | -d 384  | -d      |
| E40-LP3 | ucBGA   |         |      | --      | -P cm36 | lp384   |
| 84-CM36 | (2.5 x  |         |      | package |         |         |
|         | 2.5 mm) |         |      | cm36    |         |         |
+---------+---------+---------+------+---------+---------+---------+
| i       | 36-ball | 0.40 mm | 25   | --lp1k  | -d 1k   | -d lp1k |
| CE40-LP | ucBGA   |         |      | --      | -P cm36 |         |
| 1K-CM36 | (2.5 x  |         |      | package |         |         |
|         | 2.5 mm) |         |      | cm36    |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 49-ball | 0.40 mm | 37   | --lp384 | -d 384  | -d      |
| E40-LP3 | ucBGA   |         |      | --      | -P cm49 | lp384   |
| 84-CM49 | (3 x 3  |         |      | package |         |         |
|         | mm)     |         |      | cm49    |         |         |
+---------+---------+---------+------+---------+---------+---------+
| i       | 49-ball | 0.40 mm | 35   | --lp1k  | -d 1k   | -d lp1k |
| CE40-LP | ucBGA   |         |      | --      | -P cm49 |         |
| 1K-CM49 | (3 x 3  |         |      | package |         |         |
|         | mm)     |         |      | cm49    |         |         |
+---------+---------+---------+------+---------+---------+---------+
| i       | 81-ball | 0.40 mm | 63   | --lp1k  | -d 1k   | -d lp1k |
| CE40-LP | ucBGA   |         |      | --      | -P cm81 |         |
| 1K-CM81 | (4 x 4  |         |      | package |         |         |
|         | mm)     |         |      | cm81    |         |         |
+---------+---------+---------+------+---------+---------+---------+
| i       | 81-ball | 0.40 mm | 63   | --lp8k  | -d 8k   | -d lp8k |
| CE40-LP | ucBGA   |         |      | --      | -P      |         |
| 4K-CM81 | (4 x 4  |         |      | package | cm81:4k |         |
|         | mm)     |         |      | cm81:4k |         |         |
+---------+---------+---------+------+---------+---------+---------+
| i       | 81-ball | 0.40 mm | 63   | --lp9k  | -d 8k   | -d lp8k |
| CE40-LP | ucBGA   |         |      | --      | -P cm81 |         |
| 8K-CM81 | (4 x 4  |         |      | package |         |         |
|         | mm)     |         |      | cm81    |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 1       | 0.40 mm | 95   | --lp1k  | -d 1k   | -d lp1k |
| E40-LP1 | 21-ball |         |      | --      | -P      |         |
| K-CM121 | ucBGA   |         |      | package | cm121   |         |
|         | (5 x 5  |         |      | cm121   |         |         |
|         | mm)     |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 1       | 0.40 mm | 93   | --lp8k  | -d 8k   | -d lp8k |
| E40-LP4 | 21-ball |         |      | --      | -P      |         |
| K-CM121 | ucBGA   |         |      | package | c       |         |
|         | (5 x 5  |         |      | c       | m121:4k |         |
|         | mm)     |         |      | m121:4k |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 1       | 0.40 mm | 93   | --lp8k  | -d 8k   | -d lp8k |
| E40-LP8 | 21-ball |         |      | --      | -P      |         |
| K-CM121 | ucBGA   |         |      | package | cm121   |         |
|         | (5 x 5  |         |      | cm121   |         |         |
|         | mm)     |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 2       | 0.40 mm | 167  | --lp8k  | -d 8k   | -d lp8k |
| E40-LP4 | 25-ball |         |      | --      | -P      |         |
| K-CM225 | ucBGA   |         |      | package | c       |         |
|         | (7 x 7  |         |      | c       | m225:4k |         |
|         | mm)     |         |      | m225:4k |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 2       | 0.40 mm | 178  | --lp8k  | -d 8k   | -d lp8k |
| E40-LP8 | 25-ball |         |      | --      | -P      |         |
| K-CM225 | ucBGA   |         |      | package | cm225   |         |
|         | (7 x 7  |         |      | cm225   |         |         |
|         | mm)     |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 2       | 0.40 mm | 178  | --hx8k  | -d 8k   | -d hx8k |
| E40-HX8 | 25-ball |         |      | --      | -P      |         |
| K-CM225 | ucBGA   |         |      | package | cm225   |         |
|         | (7 x 7  |         |      | cm225   |         |         |
|         | mm)     |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 32-pin  | 0.50 mm | 21   | --lp384 | -d 384  | -d      |
| E40-LP3 | QFN (5  |         |      | --      | -P qn32 | lp384   |
| 84-QN32 | x 5 mm) |         |      | package |         |         |
|         |         |         |      | qn32    |         |         |
+---------+---------+---------+------+---------+---------+---------+
| i       | 48-pin  | 0.50 mm | 39   | --up5k  | -d 5k   | -d up5k |
| CE40-UP | QFN (7  |         |      | --      | -P sg48 |         |
| 5K-SG48 | x 7 mm) |         |      | package |         |         |
|         |         |         |      | sg48    |         |         |
+---------+---------+---------+------+---------+---------+---------+
| i       | 84-pin  | 0.50 mm | 67   | --lp1k  | -d 1k   | -d lp1k |
| CE40-LP | QFNS (7 |         |      | --      | -P qn84 |         |
| 1K-QN84 | x 7 mm) |         |      | package |         |         |
|         |         |         |      | qn84    |         |         |
+---------+---------+---------+------+---------+---------+---------+
| i       | 81-ball | 0.50 mm | 62   | --lp1k  | -d 1k   | -d lp1k |
| CE40-LP | csBGA   |         |      | --      | -P cb81 |         |
| 1K-CB81 | (5 x 5  |         |      | package |         |         |
|         | mm)     |         |      | cb81    |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 1       | 0.50 mm | 92   | --lp1k  | -d 1k   | -d lp1k |
| E40-LP1 | 21-ball |         |      | --      | -P      |         |
| K-CB121 | csBGA   |         |      | package | cb121   |         |
|         | (6 x 6  |         |      | cb121   |         |         |
|         | mm)     |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 1       | 0.50 mm | 95   | --hx1k  | -d 1k   | -d hx1k |
| E40-HX1 | 32-ball |         |      | --      | -P      |         |
| K-CB132 | csBGA   |         |      | package | cb132   |         |
|         | (8 x 8  |         |      | cb132   |         |         |
|         | mm)     |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 1       | 0.50 mm | 95   | --hx8k  | -d 8k   | -d hx8k |
| E40-HX4 | 32-ball |         |      | --      | -P      |         |
| K-CB132 | csBGA   |         |      | package | c       |         |
|         | (8 x 8  |         |      | c       | b132:4k |         |
|         | mm)     |         |      | b132:4k |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 1       | 0.50 mm | 95   | --hx8k  | -d 8k   | -d hx8k |
| E40-HX8 | 32-ball |         |      | --      | -P      |         |
| K-CB132 | csBGA   |         |      | package | cb132   |         |
|         | (8 x 8  |         |      | cb132   |         |         |
|         | mm)     |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 100-pin | 0.50 mm | 72   | --hx1k  | -d 1k   | -d hx1k |
| E40-HX1 | VQFP    |         |      | --      | -P      |         |
| K-VQ100 | (14 x   |         |      | package | vq100   |         |
|         | 14 mm)  |         |      | vq100   |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 144-pin | 0.50 mm | 96   | --hx1k  | -d 1k   | -d hx1k |
| E40-HX1 | TQFP    |         |      | --      | -P      |         |
| K-TQ144 | (20 x   |         |      | package | tq144   |         |
|         | 20 mm)  |         |      | tq144   |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 144-pin | 0.50 mm | 107  | --hx8k  | -d 8k   | -d hx8k |
| E40-HX4 | TQFP    |         |      | --      | -P      |         |
| K-TQ144 | (20 x   |         |      | package | t       |         |
|         | 20 mm)  |         |      | t       | q144:4k |         |
|         |         |         |      | q144:4k |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 1       | 0.80 mm | 93   | --hx8k  | -d 8k   | -d hx8k |
| E40-HX4 | 21-ball |         |      | --      | -P      |         |
| K-BG121 | caBGA   |         |      | package | b       |         |
|         | (9 x 9  |         |      | b       | g121:4k |         |
|         | mm)     |         |      | g121:4k |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 1       | 0.80 mm | 93   | --hx8k  | -d 8k   | -d hx8k |
| E40-HX8 | 21-ball |         |      | --      | -P      |         |
| K-BG121 | caBGA   |         |      | package | bg121   |         |
|         | (9 x 9  |         |      | bg121   |         |         |
|         | mm)     |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+
| iC      | 2       | 0.80 mm | 206  | --hx8k  | -d 8k   | -d hx8k |
| E40-HX8 | 56-ball |         |      | --      | -P      |         |
| K-CT256 | caBGA   |         |      | package | ct256   |         |
|         | (14 x   |         |      | ct256   |         |         |
|         | 14 mm)  |         |      |         |         |         |
+---------+---------+---------+------+---------+---------+---------+

Current work focuses on further improving our timing analysis flow.

How do I use the Fully Open Source iCE40 Flow?
----------------------------------------------

Synthesis for iCE40 FPGAs can be done with
`Yosys <https://github.com/YosysHQ/yosys>`__. Place-and-route can be
done with `arachne-pnr <https://github.com/YosysHQ/arachne-pnr>`__. Here
is an example script for implementing and programming the `rot example
from
arachne-pnr <https://github.com/YosysHQ/arachne-pnr/tree/master/examples/rot>`__
(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

.. _install:

Where are the Tools? How to install?
------------------------------------

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 \
                        qt5-default python3-dev libboost-all-dev cmake libeigen3-dev

On Fedora 24 the following command installs all prerequisites:

::

   sudo dnf install make automake gcc gcc-c++ kernel-devel clang bison \
                    flex readline-devel gawk tcl-devel libffi-devel git mercurial \
                    graphviz python-xdot pkgconfig python python3 libftdi-devel \
                    qt5-devel python3-devel boost-devel boost-python3-devel eigen3-devel

Note: All tools will be installed relative to /usr/local

Installing the `IceStorm Tools <https://github.com/YosysHQ/icestorm>`__
(icepack, icebox, iceprog, icetime, chip databases):

::

   git clone https://github.com/YosysHQ/icestorm.git icestorm
   cd icestorm
   make -j$(nproc)
   sudo make install

Installing `Arachne-PNR <https://github.com/YosysHQ/arachne-pnr>`__
(place&route tool, predecessor to NextPNR):

::

   git clone https://github.com/YosysHQ/arachne-pnr.git arachne-pnr
   cd arachne-pnr
   make -j$(nproc)
   sudo make install

Installing `NextPNR <https://github.com/YosysHQ/nextpnr>`__ (place&route
tool, Arachne-PNR replacement):

::

   git clone --recursive https://github.com/YosysHQ/nextpnr nextpnr
   cd nextpnr
   cmake -DARCH=ice40 -DCMAKE_INSTALL_PREFIX=/usr/local .
   make -j$(nproc)
   sudo make install

Installing `Yosys <https://github.com/YosysHQ/yosys>`__ (Verilog
synthesis):

::

   git clone https://github.com/YosysHQ/yosys.git yosys
   cd yosys
   make -j$(nproc)
   sudo make install

Both place and route tools (Arachne-PNR & NextPNR) convert the IceStorm
text chip databases into the respective PNR binary chip databases during
build. Always rebuild the PNR tools after updating your IceStorm
installation.

**Notes for Linux:** Create a file
``/etc/udev/rules.d/53-lattice-ftdi.rules`` with the following line in
it to allow uploading bit-streams to a Lattice iCEstick and/or a Lattice
iCE40-HX8K Breakout Board as unprivileged user:

::

   ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0660", GROUP="plugdev", TAG+="uaccess"

**Notes for Archlinux:** just install
`icestorm-git <https://aur.archlinux.org/packages/icestorm-git/>`__,
`arachne-pnr-git <https://aur.archlinux.org/packages/arachne-pnr-git/>`__
and `yosys-git <https://aur.archlinux.org/packages/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 <notes_osx.html>`__ to install on OSX.

Please `file an issue on
github <https://github.com/YosysHQ/icestorm/issues/new>`__ if you have
additional notes to share regarding the install procedures on the
operating system of your choice.

What are the IceStorm Tools?
----------------------------

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 <https://github.com/YosysHQ/icestorm>`__,
`Arachne-PNR <https://github.com/YosysHQ/arachne-pnr>`__, and
`Yosys <https://github.com/YosysHQ/yosys>`__.

IcePack/IceUnpack
~~~~~~~~~~~~~~~~~

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.

IceTime
~~~~~~~

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.

IceBox
~~~~~~

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.

IceProg
~~~~~~~

A small driver program for the FTDI-based programmer used on the
iCEstick and HX8K development boards.

IceMulti
~~~~~~~~

A tool for packing multiple bitstream files into one iCE40 multiboot
image file.

IcePLL
~~~~~~

A small program for calculating iCE40 PLL configuration parameters.

IceBRAM
~~~~~~~

A small program for swapping the BRAM contents in IceStorm ASCII files.
E.g. for changing the firmware image in a SoC design without re-running
synthesis and place&route.

ChipDB
~~~~~~

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
Claire Wolf. IcePack/IceUnpack is based on a reference implementation
provided by Mathias Lasser. IceMulti is written by Marcus Comstedt.*

Where do I get support or meet other IceStorm users?
----------------------------------------------------

If you have a question regarding the IceStorm flow, use the `yosys tag
on stackoverflow <http://stackoverflow.com/questions/tagged/yosys>`__ to
ask your question. If your question is a general question about Verilog
HDL design, please consider using the `verilog tag on
stackoverflow <http://stackoverflow.com/questions/tagged/verilog>`__
instead.

For general discussions go to the `Yosys
Subreddit <https://www.reddit.com/r/yosys/>`__ or `#yosys on freenode
IRC <http://webchat.freenode.net/?channels=yosys>`__.

If you have a bug report please file an issue on github. (`IceStorm
Issue Tracker <https://github.com/YosysHQ/icestorm/issues>`__, `Yosys
Issue Tracker <https://github.com/YosysHQ/yosys/issues>`__, `Arachne-PNR
Issue Tracker <https://github.com/YosysHQ/arachne-pnr/issues>`__)

.. _docs:

Where is the Documentation?
---------------------------

Recommended reading: `Lattice iCE40 LP/HX Family
Datasheet <http://www.latticesemi.com/~/media/LatticeSemi/Documents/DataSheets/iCE/iCE40LPHXFamilyDataSheet.pdf>`__,
`Lattice iCE Technology
Library <http://www.latticesemi.com/~/media/LatticeSemi/Documents/TechnicalBriefs/SBTICETechnologyLibrary201608.pdf>`__
(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.

-  `LOGIC Tile Documentation <logic_tile.html>`__
-  `IO Tile Documentation <io_tile.html>`__
-  `RAM Tile Documentation <ram_tile.html>`__
-  `The Bitstream File Format <format.html>`__
-  `The iCE40 LP384 Bit Docs <_static/bitdocs-384/index.html>`__
-  `The iCE40 HX1K Bit Docs <_static/bitdocs-1k/index.html>`__
-  `The iCE40 HX8K Bit Docs <_static/bitdocs-8k/index.html>`__
-  `Notes on UltraPlus features <ultraplus.html>`__

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 B\ y\ [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
-----

Links to related projects. Contact me at claire@clairexen.net if you
have an interesting and relevant link.

-  `J1a SwapForth built with
   IceStorm <http://www.excamera.com/sphinx/article-j1a-swapforth.html>`__
-  `Lattice iCEBlink40 Programming
   Tool <https://github.com/davidcarne/iceBurn>`__
-  `Another iCEBlink40 Programming
   Tool <https://github.com/reactive-systems/icedude>`__
-  `iCE40 layout viewer <https://github.com/knielsen/ice40_viewer>`__
-  `icedrom iCE40 netlist viewer <http://drom.io/icedrom/>`__

iCE40 Boards
~~~~~~~~~~~~

-  `Lattice iCEstick <http://www.latticesemi.com/icestick>`__
-  `Lattice iCE40-HX8K Breakout
   Board <http://www.latticesemi.com/en/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx>`__
-  `IcoBoard <http://icoboard.org/>`__
-  `wiggleport <http://wiggleport.com>`__
-  `ICEd = an Arduino Style Board, with ICE
   FPGA <https://hackaday.io/project/6636-iced-an-arduino-style-board-with-ice-fpga>`__
-  `CAT Board <https://hackaday.io/project/7982-cat-board>`__
-  `eCow-Logic pico-ITX Lattice ICE40
   board <http://opencores.org/project,ecowlogic-pico>`__
-  `Nandland Go
   Board <https://www.nandland.com/blog/go-board-introduction.html>`__
-  `myStorm board (iCE40 +
   STM32) <https://folknologylabs.wordpress.com/2016/08/17/the-lull-before-the-storm/>`__
-  `DSP iCE board (another iCE40 + STM32
   board) <https://github.com/tvelliott/dsp_ice>`__
-  `BeagleWire iCE40 FPGA BeagleBone
   cape <https://www.crowdsupply.com/qwerty-embedded-design/beaglewire>`__

Lectures and Tutorials
~~~~~~~~~~~~~~~~~~~~~~

-  `A Free and Open Source Verilog-to-Bitstream Flow for iCE40 FPGAs
   [32c3] <https://media.ccc.de/v/32c3-7139-a_free_and_open_source_verilog-to-bitstream_flow_for_ice40_fpgas>`__
-  `Synthesizing Verilog for Lattice ICE40 FPGAs (Paul
   Martin) <https://www.youtube.com/watch?v=s7fNTF8nd8A>`__
-  `A Spanish FPGA Tutorial using
   IceStorm <https://github.com/Obijuan/open-fpga-verilog-tutorial/wiki>`__
-  `IceStorm Learner’s
   Documentation <http://hedmen.org/icestorm-doc/icestorm.html>`__

Other FPGA bitstream documentation projects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-  `ECP5 bitstream documentation (Project
   Trellis) <https://github.com/SymbiFlow/prjtrellis>`__
-  `Xilinx 7-series bitstream documentation (Project
   X-Ray) <https://github.com/SymbiFlow/prjxray>`__
-  `Xilinx xc6slx9 documentation, Wolfgang
   Spraul <https://github.com/Wolfgang-Spraul/fpgatools>`__
-  `From the bitstream to the netlist, Jean-Baptiste Note and Éric
   Rannaud <http://www.fabienm.eu/flf/wp-content/uploads/2014/11/Note2008.pdf>`__
-  `Cyclone IV EP4CE6 documentation, Marek
   Vasut <http://git.bfuser.eu/?p=marex/typhoon.git;a=commit>`__

--------------

In papers and reports, please refer to Project IceStorm as follows:
Claire Wolf, Mathias Lasser. Project IceStorm.
https://prjicestorm.readthedocs.io/, e.g. using the following BibTeX
code:

::

   @MISC{IceStorm,
       author = {Claire Wolf and Mathias Lasser},
       title = {Project IceStorm},
       howpublished = "\url{https://prjicestorm.readthedocs.io/}"
   }

--------------

*Documentation mostly by Claire Wolf <claire@clairexen.net> in 2015.
Based on research by Mathias Lasser and Claire Wolf.
Buy an* `iCEstick <http://www.latticesemi.com/icestick>`__ *or*
`iCE40-HX8K Breakout
Board <http://www.latticesemi.com/en/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx>`__
*from Lattice and see what you can do with the tools and information
provided here.*