From 48154cb6f452d3bdb4da36cc267b4b6c45588dc9 Mon Sep 17 00:00:00 2001 From: Clifford Wolf Date: Sat, 18 Jul 2015 13:10:40 +0200 Subject: Imported full dev sources --- docs/index.html | 321 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 321 insertions(+) create mode 100644 docs/index.html (limited to 'docs/index.html') diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..dbd8ba6 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,321 @@ +Project IceStorm +

Project IceStorm

+ +

+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. +At the moment the focus of the project is on the HX1K-TQ144 device, but +most of the information is device-independent. +

+ +

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 +reverse engineering and as a reference platform for general purpose FPGA tool development. +

+ +

+Also, with the iCEstick there is +a cheap and easy to use development platform available, which makes the part interesting +for all kinds of projects. +

+ +

What is the Status of the Project?

+ +

+We have enough bits mapped that we can create a functional verilog model for almost all +bitstreams generated by Lattice iCEcube2 for the iCE40 HX1K-TQ144, as long as no +block memories or PLLs are used. (Both are fully documented, but the +icebox_vlog.py script does not create verilog models for them yet.) +

+ +

+Next on the TODO list: PLLs, Timing Analysis, support for HX8K chips. +

+ +

What is the Status of 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.txt
+icepack rot.txt rot.bin
+iceprog rot.bin
+ +

Where are the Tools?

+ +

+Here is the current snapshot of our toolchain: icestorm-snapshot-150526.zip
+This is work under construction and highly experimental! Use at your own risk! +

+ +

+All snapshots in reverse chronological order: +

+ + + +

IcePack/IceUnpack

+ +

+The iceunpack program converts an iCE40 .bin file into the IceBox 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. +

+ +

IceBox

+ +

+A python library and various tools for working with IceBox ASCII files and accessing +the device database. For example icebox_vlog.py converts our ASCII file +dump of a bitstream into a verilog file that implements an equivalent circuit. +

+ +

IceProg

+ +

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

+ +

+The tools are written by Clifford Wolf. IcePack/IceUnpack is based on a reference implementation provided by Mathias Lasser. +

+ +

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.py 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.py for +an example program that does that. +

+ +

+The recommended approach for learning how to use this documentation is to synthesize very simple circuits using +Lattice iCEcube2, run our toolchain on the resulting bitstream files, and analyze the results using the HTML export of the database +mentioned above. icebox_vlog.py 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. +

+ +

+For example, using the top_bitmap.bin from the following Verilog and PCF files: +

+ +
module top (input a, b, output y);
+  assign y = a & b;
+endmodule
+
+set_io a 1
+set_io b 10
+set_io y 11
+ +

+We would get something like the following icebox_explain.py output: +

+ +
$ iceunpack top_bitmap.bin top_bitmap.txt
+$ icebox_explain top_bitmap.txt
+Reading file 'top_bitmap.txt'..
+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_g1_2 io_1/D_OUT_0
+buffer logic_op_tnr_2 local_g1_2
+
+.io_tile 0 14
+IOB_1 PINTYPE_0
+IoCtrl IE_1
+IoCtrl REN_0
+buffer io_1/D_IN_0 span4_horz_28
+
+.io_tile 0 11
+IOB_0 PINTYPE_0
+IoCtrl IE_0
+IoCtrl REN_1
+
+.logic_tile 1 11
+LC_2 0000000001010101 0000
+buffer local_g1_4 lutff_2/in_3
+buffer local_g3_1 lutff_2/in_0
+buffer neigh_op_lft_4 local_g1_4
+buffer sp4_r_v_b_41 local_g3_1
+
+.logic_tile 2 14
+routing sp4_h_l_41 sp4_v_b_4
+ +

+And something like the following icebox_vlog.py output: +

+ +
$ icebox_vlog top_bitmap.txt
+// Reading file 'top_bitmap.txt'..
+
+module chip (output io_0_10_1, input io_0_11_0, input io_0_14_1);
+
+wire io_0_10_1;
+// io_0_10_1
+// (0, 10, 'io_1/D_OUT_0')
+// (0, 10, 'io_1/PAD')
+// (0, 10, 'local_g1_2')
+// (0, 10, 'logic_op_tnr_2')
+// (0, 11, 'logic_op_rgt_2')
+// (0, 12, 'logic_op_bnr_2')
+// (1, 10, 'neigh_op_top_2')
+// (1, 11, 'lutff_2/out')
+// (1, 12, 'neigh_op_bot_2')
+// (2, 10, 'neigh_op_tnl_2')
+// (2, 11, 'neigh_op_lft_2')
+// (2, 12, 'neigh_op_bnl_2')
+
+wire io_0_11_0;
+// 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_g1_4')
+// (1, 11, 'lutff_2/in_3')
+// (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 io_0_14_1;
+// io_0_14_1
+// (0, 14, 'io_1/D_IN_0')
+// (0, 14, 'io_1/PAD')
+// (0, 14, 'span4_horz_28')
+// (1, 11, 'local_g3_1')
+// (1, 11, 'lutff_2/in_0')
+// (1, 11, 'sp4_r_v_b_41')
+// (1, 12, 'sp4_r_v_b_28')
+// (1, 13, 'neigh_op_tnl_2')
+// (1, 13, 'neigh_op_tnl_6')
+// (1, 13, 'sp4_r_v_b_17')
+// (1, 14, 'neigh_op_lft_2')
+// (1, 14, 'neigh_op_lft_6')
+// (1, 14, 'sp4_h_r_41')
+// (1, 14, 'sp4_r_v_b_4')
+// (1, 15, 'neigh_op_bnl_2')
+// (1, 15, 'neigh_op_bnl_6')
+// (2, 10, 'sp4_v_t_41')
+// (2, 11, 'sp4_v_b_41')
+// (2, 12, 'sp4_v_b_28')
+// (2, 13, 'sp4_v_b_17')
+// (2, 14, 'sp4_h_l_41')
+// (2, 14, 'sp4_v_b_4')
+
+assign io_0_10_1 = /* LUT    1 11  2 */ io_0_11_0 ? io_0_14_1 : 0;
+
+endmodule
+ +

+

+

+ +

+In papers and reports, please refer to Project IceStorm as follows: Clifford Wolf, Mathias Lasser. Project IceStorm. http://www.clifford.at/icestorm/, +e.g. using the following BibTeX code: +

+ +
@MISC{IceStorm,
+	author = {Clifford Wolf and Mathias Lasser},
+	title = {Project IceStorm},
+	howpublished = "\url{http://www.clifford.at/icestorm/}"
+}
+ +

+

+

+ +

+Documentation mostly by Clifford Wolf <clifford@clifford.at> in 2015. Based on research by Mathias Lasser and Clifford Wolf.
+Buy an iCEstick from Lattice and see what you can do with the information provided here. Buy a few because you might break some.. +

-- cgit v1.2.3