aboutsummaryrefslogtreecommitdiffstats
path: root/docs/index.html
diff options
context:
space:
mode:
authorClifford Wolf <clifford@clifford.at>2015-08-06 11:11:31 +0200
committerClifford Wolf <clifford@clifford.at>2015-08-06 11:11:31 +0200
commit99d93dae2296d86e77974f5607af3d92a3fc7b6a (patch)
tree30f452c50a73e74a7a50b1d5e817743d09daf747 /docs/index.html
parentc2edd14772dd39967ad501d2aba475dc3ad29e79 (diff)
downloadicestorm-99d93dae2296d86e77974f5607af3d92a3fc7b6a.tar.gz
icestorm-99d93dae2296d86e77974f5607af3d92a3fc7b6a.tar.bz2
icestorm-99d93dae2296d86e77974f5607af3d92a3fc7b6a.zip
Improved documentation
Diffstat (limited to 'docs/index.html')
-rw-r--r--docs/index.html132
1 files changed, 71 insertions, 61 deletions
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):
<pre style="padding-left: 3em">
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
</pre>
<p>
@@ -92,6 +92,11 @@ cd yosys
make -j$(nproc)
sudo make install</pre>
+<p>
+Note: The Arachne-PNR build depends on files installed by IceStorm. Always rebuild Arachne-PNR
+after updating your IceStorm installation.
+</p>
+
<h2>What are the IceStorm Tools?</h2>
<h3>IcePack/IceUnpack</h3>
@@ -106,7 +111,7 @@ that has blocks of <tt>0</tt> and <tt>1</tt> for the config bits for each tile i
<p>
A python library and various tools for working with IceBox ASCII files and accessing
-the device database. For example <tt>icebox_vlog.py</tt> converts our ASCII file
+the device database. For example <tt>icebox_vlog</tt> converts our ASCII file
dump of a bitstream into a Verilog file that implements an equivalent circuit.
</p>
@@ -180,7 +185,7 @@ line, <tt>B0[0]</tt> the first bit in the first line, and <tt>B15[53]</tt> the l
</p>
<p>
-The <tt>icebox_explain.py</tt> program can be used to turn this block of config bits into a description of the cell
+The <tt>icebox_explain</tt> program can be used to turn this block of config bits into a description of the cell
configuration:
</p>
@@ -194,39 +199,49 @@ buffer sp12_h_r_20 local_g1_4</pre>
<p>
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 <tt>icebox_chipdb.py</tt> for
+to export this database into a format that fits the target application. See <tt>icebox_chipdb</tt> for
an example program that does that.
</p>
<p>
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 <tt>icebox_explain</tt> on the resulting bitstream files, and analyze the
results using the HTML export of the database mentioned above.
-<tt>icebox_vlog.py</tt> can be used to convert the bitstream to Verilog. The
+<tt>icebox_vlog</tt> 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.
</p>
<p>
-For example, using the <tt>top_bitmap.bin</tt> from the following Verilog and PCF files:
+For example, consider the following Verilog and PCF files:
</p>
-<pre style="padding-left: 3em">module top (input a, b, output y);
+<pre style="padding-left: 3em">// example.v
+module top (input a, b, output y);
assign y = a &amp; b;
endmodule
+# example.pcf
set_io a 1
set_io b 10
set_io y 11</pre>
<p>
-We would get something like the following <tt>icebox_explain.py</tt> output:
+And run them through Yosys, Arachne-PNR and IcePack:
+</p>
+
+<pre style="padding-left: 3em">$ 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
+</pre>
+
+<p>
+We would get something like the following <tt>icebox_explain</tt> output:
</p>
-<pre style="padding-left: 3em">$ iceunpack top_bitmap.bin top_bitmap.txt
-$ icebox_explain top_bitmap.txt
-Reading file 'top_bitmap.txt'..
+<pre style="padding-left: 3em">$ 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</pre>
+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</pre>
<p>
-And something like the following <tt>icebox_vlog.py</tt> output:
+And something like the following <tt>icebox_vlog</tt> output:
</p>
-<pre style="padding-left: 3em">$ icebox_vlog top_bitmap.txt
-// Reading file 'top_bitmap.txt'..
+<pre style="padding-left: 3em">$ 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</pre>