From 42be8d5bf0c2c6f3422b14cc4d264da7781da43b Mon Sep 17 00:00:00 2001 From: Miodrag Milanovic Date: Fri, 29 Nov 2024 09:04:06 +0100 Subject: Start converting documentation to Sphinx --- docs/index.html | 590 -------------------------------------------------------- 1 file changed, 590 deletions(-) delete mode 100644 docs/index.html (limited to 'docs/index.html') diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 9f6b6eb..0000000 --- a/docs/index.html +++ /dev/null @@ -1,590 +0,0 @@ - - - -Project IceStorm - -

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 of the IceStorm flow at 32C3 (Video on Youtube).
-2015-07-19: Released support for 8k chips. Moved IceStorm source code to GitHub.
-2015-05-27: We have a working fully Open Source flow with Yosys and Arachne-pnr! Video: http://youtu.be/yUiNlmvVOq8
-2015-04-13: Complete rewrite of IceUnpack, added IcePack, some major documentation updates
-2015-03-22: First public release and short YouTube video demonstrating our work: http://youtu.be/u1ZHcSNDQMM -

- -

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, 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 there is -a cheap and easy to use development platform available, which makes the part interesting -for all kinds of projects. (The iCEstick features an HX1K device. Lattice also sells an iCE40-HX8K -Breakout Board featuring an HX8K chip.) -

- -

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): -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PartPackagePin SpacingI/Osnextpnr optsarachne-pnr optsicetime opts
iCE40-LP1K-SWG16TR16-ball WLCSP (1.40 x 1.48 mm)0.35 mm10--lp1k --package swg16tr-d 1k -P swg16tr-d lp1k
iCE40-UP3K-UWG3030-ball WLCSP (2.15 x 2.55 mm)0.40 mm21--up5k --package uwg30-d 5k -P uwg30-d up5k
iCE40-UP5K-UWG3030-ball WLCSP (2.15 x 2.55 mm)0.40 mm21--up5k --package uwg30-d 5k -P uwg30-d up5k
iCE40-LP384-CM3636-ball ucBGA (2.5 x 2.5 mm)0.40 mm25--lp384 --package cm36-d 384 -P cm36-d lp384
iCE40-LP1K-CM3636-ball ucBGA (2.5 x 2.5 mm)0.40 mm25--lp1k --package cm36-d 1k -P cm36-d lp1k
iCE40-LP384-CM4949-ball ucBGA (3 x 3 mm)0.40 mm37--lp384 --package cm49-d 384 -P cm49-d lp384
iCE40-LP1K-CM4949-ball ucBGA (3 x 3 mm)0.40 mm35--lp1k --package cm49-d 1k -P cm49-d lp1k
iCE40-LP1K-CM8181-ball ucBGA (4 x 4 mm)0.40 mm63--lp1k --package cm81-d 1k -P cm81-d lp1k
iCE40-LP4K-CM8181-ball ucBGA (4 x 4 mm)0.40 mm63--lp8k --package cm81:4k-d 8k -P cm81:4k-d lp8k
iCE40-LP8K-CM8181-ball ucBGA (4 x 4 mm)0.40 mm63--lp9k --package cm81-d 8k -P cm81-d lp8k
iCE40-LP1K-CM121121-ball ucBGA (5 x 5 mm)0.40 mm95--lp1k --package cm121-d 1k -P cm121-d lp1k
iCE40-LP4K-CM121121-ball ucBGA (5 x 5 mm)0.40 mm93--lp8k --package cm121:4k-d 8k -P cm121:4k-d lp8k
iCE40-LP8K-CM121121-ball ucBGA (5 x 5 mm)0.40 mm93--lp8k --package cm121-d 8k -P cm121-d lp8k
iCE40-LP4K-CM225225-ball ucBGA (7 x 7 mm)0.40 mm167--lp8k --package cm225:4k-d 8k -P cm225:4k-d lp8k
iCE40-LP8K-CM225225-ball ucBGA (7 x 7 mm)0.40 mm178--lp8k --package cm225-d 8k -P cm225-d lp8k
iCE40-HX8K-CM225225-ball ucBGA (7 x 7 mm)0.40 mm178--hx8k --package cm225-d 8k -P cm225-d hx8k
iCE40-LP384-QN3232-pin QFN (5 x 5 mm)0.50 mm21--lp384 --package qn32-d 384 -P qn32-d lp384
iCE40-UP5K-SG4848-pin QFN (7 x 7 mm)0.50 mm39--up5k --package sg48-d 5k -P sg48-d up5k
iCE40-LP1K-QN8484-pin QFNS (7 x 7 mm)0.50 mm67--lp1k --package qn84-d 1k -P qn84-d lp1k
iCE40-LP1K-CB8181-ball csBGA (5 x 5 mm)0.50 mm62--lp1k --package cb81-d 1k -P cb81-d lp1k
iCE40-LP1K-CB121121-ball csBGA (6 x 6 mm)0.50 mm92--lp1k --package cb121-d 1k -P cb121-d lp1k
iCE40-HX1K-CB132132-ball csBGA (8 x 8 mm)0.50 mm95--hx1k --package cb132-d 1k -P cb132-d hx1k
iCE40-HX4K-CB132132-ball csBGA (8 x 8 mm)0.50 mm95--hx8k --package cb132:4k-d 8k -P cb132:4k-d hx8k
iCE40-HX8K-CB132132-ball csBGA (8 x 8 mm)0.50 mm95--hx8k --package cb132-d 8k -P cb132-d hx8k
iCE40-HX1K-VQ100100-pin VQFP (14 x 14 mm)0.50 mm72--hx1k --package vq100-d 1k -P vq100-d hx1k
iCE40-HX1K-TQ144144-pin TQFP (20 x 20 mm)0.50 mm96--hx1k --package tq144-d 1k -P tq144-d hx1k
iCE40-HX4K-TQ144144-pin TQFP (20 x 20 mm)0.50 mm107--hx8k --package tq144:4k-d 8k -P tq144:4k-d hx8k
iCE40-HX4K-BG121121-ball caBGA (9 x 9 mm)0.80 mm93--hx8k --package bg121:4k-d 8k -P bg121:4k-d hx8k
iCE40-HX8K-BG121121-ball caBGA (9 x 9 mm)0.80 mm93--hx8k --package bg121-d 8k -P bg121-d hx8k
iCE40-HX8K-CT256256-ball caBGA (14 x 14 mm)0.80 mm206--hx8k --package ct256-d 8k -P ct256-d hx8k
- -

-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. -Place-and-route can be done with arachne-pnr. -Here is an example script for implementing and programming the rot example from -arachne-pnr (this example targets the iCEstick development board): -

- -
yosys -p "synth_ice40 -blif rot.blif" rot.v
-arachne-pnr -d 1k -p rot.pcf rot.blif -o rot.asc
-icepack rot.asc rot.bin
-iceprog rot.bin
- -

-A simple timing analysis report can be generated using the icetime utility: -

- -
icetime -tmd hx1k rot.asc
- -

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 (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 (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 (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 (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, arachne-pnr-git and yosys-git from the Arch User Repository (no need to follow the install instructions above). -

- -

-Notes for OSX: Please follow the additional instructions for OSX to install on OSX. -

- -

-Please file an issue on github if you have additional notes to -share regarding the install procedures on the operating system of your choice. -

- -

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, Arachne-PNR, and 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 -to ask your question. If your question is a general question about Verilog HDL design, please consider using the -verilog tag on stackoverflow instead. -

- -

-For general discussions go to the Yosys Subreddit or #yosys on freenode IRC. -

- -

-If you have a bug report please file an issue on github. (IceStorm Issue Tracker, -Yosys Issue Tracker, Arachne-PNR Issue Tracker) -

- -

Where is the Documentation?

- -

-Recommended reading: -Lattice iCE40 LP/HX Family Datasheet, -Lattice iCE Technology Library -(Especially the three pages on "Architecture Overview", "PLB Blocks", "Routing", and "Clock/Control Distribution Network" in -the Lattice iCE40 LP/HX Family Datasheet. Read that first, then come back here.) -

- -

-The FPGA fabric is divided into tiles. There are IO, RAM and LOGIC tiles. -

- - - -

-The iceunpack program can be used to convert the bitstream into an ASCII file -that has a block of 0 and 1 characters for each tile. For example: -

- -
.logic_tile 12 12
-000000000000000000000000000000000000000000000000000000
-000000000000000000000011010000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000001011000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000001000001000010101010000000000
-000000000000000000000000000101010000101010100000000000
- -

-This bits are referred to as By[x] in the documentation. For example, B0 is the first -line, B0[0] the first bit in the first line, and B15[53] the last bit in the last line. -

- -

-The icebox_explain program can be used to turn this block of config bits into a description of the cell -configuration: -

- -
.logic_tile 12 12
-LC_7 0101010110101010 0000
-buffer local_g0_2 lutff_7/in_3
-buffer local_g1_4 lutff_7/in_0
-buffer sp12_h_r_18 local_g0_2
-buffer sp12_h_r_20 local_g1_4
- -

-IceBox contains a database of the wires and configuration bits that can be found in iCE40 tiles. This database can be accessed -via the IceBox Python API. But IceBox is a large hack. So it is recommended to only use the IceBox API -to export this database into a format that fits the target application. See icebox_chipdb for -an example program that does that. -

- -

-The recommended approach for learning how to use this documentation is to -synthesize very simple circuits using Yosys and Arachne-pnr, run the icestorm -tool icebox_explain on the resulting bitstream files, and analyze the -results using the HTML export of the database mentioned above. -icebox_vlog can be used to convert the bitstream to Verilog. The -output file of this tool will also outline the signal paths in comments added -to the generated Verilog code. -

- -

-For example, consider the following Verilog and PCF files: -

- -
// example.v
-module top (input a, b, output y);
-  assign y = a & b;
-endmodule
-
-# example.pcf
-set_io a 1
-set_io b 10
-set_io y 11
- -

-And run them through Yosys, Arachne-PNR and IcePack: -

- -
$ yosys -p 'synth_ice40 -top top -blif example.blif' example.v
-$ arachne-pnr -d 1k -o example.asc -p example.pcf example.blif
-$ icepack example.asc example.bin
-
- -

-We would get something like the following icebox_explain output: -

- -
$ icebox_explain example.asc
-Reading file 'example.asc'..
-Fabric size (without IO tiles): 12 x 16
-
-.io_tile 0 10
-IOB_1 PINTYPE_0
-IOB_1 PINTYPE_3
-IOB_1 PINTYPE_4
-IoCtrl IE_0
-IoCtrl IE_1
-IoCtrl REN_0
-buffer local_g0_5 io_1/D_OUT_0
-buffer logic_op_tnr_5 local_g0_5
-
-.io_tile 0 14
-IOB_1 PINTYPE_0
-IoCtrl IE_1
-IoCtrl REN_0
-buffer io_1/D_IN_0 span4_vert_b_6
-
-.io_tile 0 11
-IOB_0 PINTYPE_0
-IoCtrl IE_0
-IoCtrl REN_1
-routing span4_vert_t_14 span4_horz_13
-
-.logic_tile 1 11
-LC_5 0001000000000000 0000
-buffer local_g0_0 lutff_5/in_1
-buffer local_g3_0 lutff_5/in_0
-buffer neigh_op_lft_0 local_g0_0
-buffer sp4_h_r_24 local_g3_0
- -

-And something like the following icebox_vlog output: -

- -
$ icebox_vlog -p example.pcf example.asc
-// Reading file 'example.asc'..
-
-module chip (output y, input b, input a);
-
-wire y;
-// io_0_10_1
-// (0, 10, 'io_1/D_OUT_0')
-// (0, 10, 'io_1/PAD')
-// (0, 10, 'local_g0_5')
-// (0, 10, 'logic_op_tnr_5')
-// (0, 11, 'logic_op_rgt_5')
-// (0, 12, 'logic_op_bnr_5')
-// (1, 10, 'neigh_op_top_5')
-// (1, 11, 'lutff_5/out')
-// (1, 12, 'neigh_op_bot_5')
-// (2, 10, 'neigh_op_tnl_5')
-// (2, 11, 'neigh_op_lft_5')
-// (2, 12, 'neigh_op_bnl_5')
-
-wire b;
-// io_0_11_0
-// (0, 11, 'io_0/D_IN_0')
-// (0, 11, 'io_0/PAD')
-// (1, 10, 'neigh_op_tnl_0')
-// (1, 10, 'neigh_op_tnl_4')
-// (1, 11, 'local_g0_0')
-// (1, 11, 'lutff_5/in_1')
-// (1, 11, 'neigh_op_lft_0')
-// (1, 11, 'neigh_op_lft_4')
-// (1, 12, 'neigh_op_bnl_0')
-// (1, 12, 'neigh_op_bnl_4')
-
-wire a;
-// io_0_14_1
-// (0, 11, 'span4_horz_13')
-// (0, 11, 'span4_vert_t_14')
-// (0, 12, 'span4_vert_b_14')
-// (0, 13, 'span4_vert_b_10')
-// (0, 14, 'io_1/D_IN_0')
-// (0, 14, 'io_1/PAD')
-// (0, 14, 'span4_vert_b_6')
-// (0, 15, 'span4_vert_b_2')
-// (1, 11, 'local_g3_0')
-// (1, 11, 'lutff_5/in_0')
-// (1, 11, 'sp4_h_r_24')
-// (1, 13, 'neigh_op_tnl_2')
-// (1, 13, 'neigh_op_tnl_6')
-// (1, 14, 'neigh_op_lft_2')
-// (1, 14, 'neigh_op_lft_6')
-// (1, 15, 'neigh_op_bnl_2')
-// (1, 15, 'neigh_op_bnl_6')
-// (2, 11, 'sp4_h_r_37')
-// (3, 11, 'sp4_h_l_37')
-
-assign y = /* LUT    1 11  5 */ b ? a : 0;
-
-endmodule
- -

Links

- -

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

- - - -

iCE40 Boards

- - - -

Lectures and Tutorials

- - - -

Other FPGA bitstream documentation projects

- - - -
- -

-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 or iCE40-HX8K Breakout Board from Lattice and see what you can do with the tools and information provided here. -

- - -- cgit v1.2.3