diff options
Diffstat (limited to 'docs/source/overview.rst')
| -rw-r--r-- | docs/source/overview.rst | 740 |
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.* |