From 99d93dae2296d86e77974f5607af3d92a3fc7b6a Mon Sep 17 00:00:00 2001 From: Clifford Wolf Date: Thu, 6 Aug 2015 11:11:31 +0200 Subject: Improved documentation --- docs/index.html | 132 ++++++++++++++++++++++++++++++-------------------------- 1 file changed, 71 insertions(+), 61 deletions(-) (limited to 'docs/index.html') diff --git a/docs/index.html b/docs/index.html index 8a38266..513e3dc 100644 --- a/docs/index.html +++ b/docs/index.html @@ -62,7 +62,7 @@ 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 libftdi-dev
+                     xdot pkg-config python python3 libftdi-dev

@@ -92,6 +92,11 @@ cd yosys make -j$(nproc) sudo make install +

+Note: The Arachne-PNR build depends on files installed by IceStorm. Always rebuild Arachne-PNR +after updating your IceStorm installation. +

+

What are the IceStorm Tools?

IcePack/IceUnpack

@@ -106,7 +111,7 @@ that has blocks of 0 and 1 for the config bits for each tile i

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 +the device database. For example icebox_vlog converts our ASCII file dump of a bitstream into a Verilog file that implements an equivalent circuit.

@@ -180,7 +185,7 @@ line, B0[0] the first bit in the first line, and B15[53] the l

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

@@ -194,39 +199,49 @@ 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 +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 (or Lattice -iCEcube2), run our toolchain on the resulting bitstream files, and analyze the +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.py can be used to convert the bitstream to Verilog. The +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. +to the generated Verilog code.

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

-
module top (input a, b, output y);
+
// 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

 
 

-We would get something like the following icebox_explain.py output:
+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.txt -p example.pcf example.blif
+$ icepack example.txt example.bin
+

+
+

+We would get something like the following icebox_explain output:
 

 
-
$ iceunpack top_bitmap.bin top_bitmap.txt
-$ icebox_explain top_bitmap.txt
-Reading file 'top_bitmap.txt'..
+
$ icebox_explain example.txt
+Reading file 'example.txt'..
 Fabric size (without IO tiles): 12 x 16
 
 .io_tile 0 10
@@ -236,93 +251,88 @@ 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
+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_horz_28
+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_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

+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.py output:
+And something like the following icebox_vlog output:
 

 
-
$ icebox_vlog top_bitmap.txt
-// Reading file 'top_bitmap.txt'..
+
$ icebox_vlog -p example.pcf example.txt
+// Reading file 'example.txt'..
 
-module chip (output io_0_10_1, input io_0_11_0, input io_0_14_1);
+module chip (output y, input b, input a);
 
-wire io_0_10_1;
+wire y;
 // 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;
+// (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_g1_4')
-// (1, 11, 'lutff_2/in_3')
+// (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 io_0_14_1;
+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_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')
+// (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, 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;
+// (2, 11, 'sp4_h_r_37')
+// (3, 11, 'sp4_h_l_37')
+
+assign y = /* LUT    1 11  5 */ b ? a : 0;
 
 endmodule

 
-- 
cgit v1.2.3