mirror of https://github.com/YosysHQ/icestorm.git
748 lines
31 KiB
ReStructuredText
748 lines
31 KiB
ReStructuredText
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 Guix:** just install
|
||
`icestorm <https://hpc.guix.info/package/icestorm/>`__,
|
||
`nextpnr-ice40 <https://hpc.guix.info/package/nextpnr-ice40/>`__
|
||
and `yosys <https://hpc.guix.info/package/yosys>`__
|
||
(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.*
|