Merge pull request #341 from YosysHQ/docs

Convert documentation to readthedocs

1 files changed, 740 insertions, 0 deletions

diff --git a/docs/source/overview.rst b/docs/source/overview.rst
new file mode 100644
index 0000000..40dab79
--- /dev/null
+++ b/docs/source/overview.rst
@@ -0,0 +1,740 @@
+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 <http://bygone.clairexen.net/papers/2015/icestorm-flow/>`__
+  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 <http://bygone.clairexen.net/yosys/>`__ and
+  `Arachne-pnr <https://github.com/cseed/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 <http://bygone.clairexen.net/yosys/>`__,
+`Arachne-pnr <https://github.com/cseed/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 <http://bygone.clairexen.net/yosys/>`__. Place-and-route can be
+done with `arachne-pnr <https://github.com/cseed/arachne-pnr>`__. Here
+is an example script for implementing and programming the `rot example
+from
+arachne-pnr <https://github.com/cseed/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/cseed/arachne-pnr>`__
+(place&route tool, predecessor to NextPNR):
+
+::
+
+   git clone https://github.com/cseed/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 <http://bygone.clairexen.net/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/cseed/arachne-pnr>`__, and
+`Yosys <http://bygone.clairexen.net/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/cseed/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 HX1K Bit Docs <bitdocs-1k/>`__
+-  `The iCE40 HX8K Bit Docs <bitdocs-8k/>`__
+-  `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.
+http://bygone.clairexen.net/icestorm/, e.g. using the following BibTeX
+code:
+
+::
+
+   @MISC{IceStorm,
+       author = {Claire Wolf and Mathias Lasser},
+       title = {Project IceStorm},
+       howpublished = "\url{http://bygone.clairexen.net/icestorm/}"
+   }
+
+--------------
+
+*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.*