1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
|
<!DOCTYPE html>
<html><head><meta charset="UTF-8">
<title>Project IceStorm</title>
</head><body>
<h1>Project IceStorm</h1>
<p>
<b>2016-01-17:</b> First release of IceTime timing analysis. Video: <a href="https://youtu.be/IG5CpFJRnOk">https://youtu.be/IG5CpFJRnOk</a><br/>
<b>2015-12-27:</b> <a href="http://www.clifford.at/papers/2015/icestorm-flow/">Presentation</a> of the IceStorm flow at 32C3 (<a href="https://www.youtube.com/watch?v=9rYiGDDUIzg">Video on Youtube</a>).<br/>
<b>2015-07-19:</b> Released support for 8k chips. Moved IceStorm source code to GitHub.<br/>
<b>2015-05-27:</b> We have a working fully Open Source flow with <a href="http://www.clifford.at/yosys/">Yosys</a> and <a href="https://github.com/cseed/arachne-pnr">Arachne-pnr</a>! Video: <a href="http://youtu.be/yUiNlmvVOq8">http://youtu.be/yUiNlmvVOq8</a><br/>
<b>2015-04-13:</b> Complete rewrite of IceUnpack, added IcePack, some major documentation updates<br/>
<b>2015-03-22:</b> First public release and short YouTube video demonstrating our work: <a href="http://youtu.be/u1ZHcSNDQMM">http://youtu.be/u1ZHcSNDQMM</a>
</p>
<h2>What is Project IceStorm?</h2>
<p>
Project IceStorm aims at reverse engineering and 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 and HX8K-CT256 devices, but most of the information is
device-independent.
</p>
<h2>Why the Lattice iCE40?</h2>
<p>
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.
</p>
<p>
Also, with the <a href="http://www.latticesemi.com/icestick">iCEstick</a> there is
a cheap and easy to use development platform available, which makes the part interesting
for all kinds of projects.
</p>
<h2>What is the Status of the Project?</h2>
<p>
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
and the iCE40 HX8K-CT256, and can create bitstreams for this parts using our
own tool-chain.
</p>
<p>
The next milestones for the project are timing analysis and support for more
parts from the iCE40 family.
</p>
<h2>What is the Status of the Fully Open Source iCE40 Flow?</h2>
<p>
Synthesis for iCE40 FPGAs can be done with <a href="http://www.clifford.at/yosys/">Yosys</a>.
Place-and-route can be done with <a href="https://github.com/cseed/arachne-pnr">arachne-pnr</a>.
Here is an example script for implementing and programming the <a
href="https://github.com/cseed/arachne-pnr/tree/master/examples/rot">rot example from
arachne-pnr</a> (this example targets the iCEstick development board):
</p>
<pre style="padding-left: 3em">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</pre>
<h2>Where are the Tools? How to install?</h2>
<p>
Installing prerequisites (this command is for Ubuntu 14.04):
</p>
<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 python3 libftdi-dev
</pre>
<p>
Installing the <a href="https://github.com/cliffordwolf/icestorm">IceStorm Tools</a> (icepack, icebox, iceprog):
</p>
<pre style="padding-left: 3em">git clone https://github.com/cliffordwolf/icestorm.git icestorm
cd icestorm
make -j$(nproc)
sudo make install</pre>
<p>
Installing <a href="https://github.com/cseed/arachne-pnr">Arachne-PNR</a> (the place&route tool):
</p>
<pre style="padding-left: 3em">git clone https://github.com/cseed/arachne-pnr.git arachne-pnr
cd arachne-pnr
make -j$(nproc)
sudo make install</pre>
<p>
Installing <a href="http://www.clifford.at/yosys/">Yosys</a> (Verilog synthesis):
</p>
<pre style="padding-left: 3em">git clone https://github.com/cliffordwolf/yosys.git yosys
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>
<p>
<b>Notes for Archlinux:</b> just install <a href="https://aur.archlinux.org/packages/icestorm-git/">icestorm-git</a>, <a href="https://aur.archlinux.org/packages/arachne-pnr-git/">arachne-pnr-git</a> and <a href="https://aur.archlinux.org/packages/yosys-git/">yosys-git</a> from the Arch User Repository (no need to follow the install instructions above).
</p>
<p>
<b>Notes for OSX:</b> Please follow the <a href="notes_osx.html">additional instructions for OSX</a> to install on OSX.
</p>
<p>
Please <a href="https://github.com/cliffordwolf/icestorm/issues/new">file an issue on github</a> if you have additional notes to
share regarding the install procedures on the operating system of your choice.
</p>
<h2>What are the IceStorm Tools?</h2>
<h3>IcePack/IceUnpack</h3>
<p>
The <span style="font-family:monospace">iceunpack</span> program converts an iCE40 <span style="font-family:monospace">.bin</span> file into the IceBox ASCII format
that has blocks of <span style="font-family:monospace">0</span> and <span style="font-family:monospace">1</span> for the config bits for each tile in the chip. The
<span style="font-family:monospace">icepack</span> program converts such an ASCII file back to an iCE40 <span style="font-family:monospace">.bin</span> file.
</p>
<h3>IceTime</h3>
<p>
The <span style="font-family:monospace">icetime</span> program is an iCE40 timing analysis tool. It reads designs in IceBox 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.
</p>
<h3>IceBox</h3>
<p>
A python library and various tools for working with IceBox ASCII files and accessing
the device database. For example <span style="font-family:monospace">icebox_vlog</span> converts our ASCII file
dump of a bitstream into a Verilog file that implements an equivalent circuit.
</p>
<h3>IceProg</h3>
<p>
A small driver program for the FTDI-based programmer used on the iCEstick and HX8K development boards.
</p>
<h3>IceMulti</h3>
<p>
A tool for packing multiple bitstream files into one iCE40 multiboot image file.
</p>
<h3>ChipDB</h3>
<p>
The IceStorm Makefile builds and installs two files: <span style="font-family:monospace">chipdb-1k.txt</span> and <span style="font-family:monospace">chipdb-8k.txt</span>.
This files contain all the relevant information for arachne-pnr to place&route a design and
create an IceBox ASCII file for the placed and routed design.
</p>
<p>
<i>The IcePack/IceUnpack, IceBox, and IceProg are written by Clifford Wolf. IcePack/IceUnpack is based on a reference implementation provided by Mathias Lasser. IceMulti is written by Marcus Comstedt.</i>
</p>
<h2>Where is the Documentation?</h2>
<p>
Recommended reading:
<a href="http://www.latticesemi.com/~/media/LatticeSemi/Documents/DataSheets/iCE/iCE40LPHXFamilyDataSheet.pdf">Lattice iCE40 LP/HX Family Datasheet</a>,
<a href="http://www.latticesemi.com/~/media/LatticeSemi/Documents/TechnicalBriefs/SBTICETechnologyLibrary201504.pdf">Lattice iCE Technology Library</a>
(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.)
</p>
<p>
The FPGA fabric is divided into tiles. There are IO, RAM and LOGIC tiles.
</p>
<ul>
<li><a href="logic_tile.html">LOGIC Tile Documentation</a></li>
<li><a href="io_tile.html">IO Tile Documentation</a></li>
<li><a href="ram_tile.html">RAM Tile Documentation</a></li>
<li><a href="format.html">The Bitstream File Format</a></li>
<li><a href="bitdocs-1k/">The iCE40 HX1K Bit Docs</a></li>
<li><a href="bitdocs-8k/">The iCE40 HX8K Bit Docs</a></li>
</ul>
<p>
The <span style="font-family:monospace">iceunpack</span> program can be used to convert the bitstream into an ASCII file
that has a block of <span style="font-family:monospace">0</span> and <span style="font-family:monospace">1</span> characters for each tile. For example:
</p>
<pre style="padding-left: 3em">.logic_tile 12 12
000000000000000000000000000000000000000000000000000000
000000000000000000000011010000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000001011000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000001000001000010101010000000000
000000000000000000000000000101010000101010100000000000</pre>
<p>
This bits are referred to as <span style="font-family:monospace">B<i>y</i>[<i>x</i>]</span> in the documentation. For example, <span style="font-family:monospace">B0</span> is the first
line, <span style="font-family:monospace">B0[0]</span> the first bit in the first line, and <span style="font-family:monospace">B15[53]</span> the last bit in the last line.
</p>
<p>
The <span style="font-family:monospace">icebox_explain</span> program can be used to turn this block of config bits into a description of the cell
configuration:
</p>
<pre style="padding-left: 3em">.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</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 <span style="font-family:monospace">icebox_chipdb</span> 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, run the icestorm
tool <span style="font-family:monospace">icebox_explain</span> on the resulting bitstream files, and analyze the
results using the HTML export of the database mentioned above.
<span style="font-family:monospace">icebox_vlog</span> 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.
</p>
<p>
For example, consider the following Verilog and PCF files:
</p>
<pre style="padding-left: 3em">// 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</pre>
<p>
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.asc -p example.pcf example.blif
$ icepack example.asc example.bin
</pre>
<p>
We would get something like the following <span style="font-family:monospace">icebox_explain</span> output:
</p>
<pre style="padding-left: 3em">$ 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</pre>
<p>
And something like the following <span style="font-family:monospace">icebox_vlog</span> output:
</p>
<pre style="padding-left: 3em">$ 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</pre>
<h2>Links</h2>
<p>
Links to related projects. Contact me at clifford@clifford.at if you have an interesting and relevant link.
</p>
<ul>
<li><a href="http://www.excamera.com/sphinx/article-j1a-swapforth.html">J1a SwapForth built with IceStorm</a>
<li><a href="https://github.com/Obijuan/open-fpga-verilog-tutorial/wiki">A Spanish FPGA Tutorial using IceStorm</a>
<li><a href="https://github.com/davidcarne/iceBurn">Lattice iCEBlink40 Programming Tool</a>
</ul>
<h3>iCE40 Boards</h3>
<ul>
<li><a href="http://www.latticesemi.com/icestick">Lattice iCEstick</a>
<li><a href="http://icoboard.org/">IcoBoard</a>
<li><a href="http://wiggleport.com">wiggleport</a>
<li><a href="https://hackaday.io/project/6636-iced-an-arduino-style-board-with-ice-fpga">ICEd = an Arduino Style Board, with ICE FPGA</a>
<li><a href="https://hackaday.io/project/7982-cat-board">CAT Board</a>
<li><a href="http://opencores.org/project,ecowlogic-pico">eCow-Logic pico-ITX Lattice ICE40 board</a>
<li><a href="https://www.nandland.com/blog/go-board-introduction.html">Nandland Go Board</a>
</ul>
<h3>Other FPGA reverse engineering projects</h3>
<ul>
<li><a href="https://github.com/Wolfgang-Spraul/fpgatools">Xilinx xc6slx9 reverse engineering, Wolfgang Spraul</a>
<li><a href="http://www.fabienm.eu/flf/wp-content/uploads/2014/11/Note2008.pdf">From the bitstream to the netlist, Jean-Baptiste Note and Éric Rannaud</a>
</ul>
<hr>
<p>
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:
</p>
<pre>@MISC{IceStorm,
author = {Clifford Wolf and Mathias Lasser},
title = {Project IceStorm},
howpublished = "\url{http://www.clifford.at/icestorm/}"
}</pre>
<hr>
<p>
<i>Documentation mostly by Clifford Wolf <clifford@clifford.at> in 2015. Based on research by Mathias Lasser and Clifford Wolf.<br/>
Buy an <a href="http://www.latticesemi.com/icestick">iCEstick</a> from Lattice and see what you can do with the information provided here.</i>
</p>
</body></html>
|
