Project IceStorm

https://github.com/yosyshq/icestorm
Admin
Project IceStorm aims to document the bitstream format of Lattice iCE40 FPGAs and provide simple...
Tokens:9,086
Snippets:122
Trust Score:9.2
License:ISC
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install IceStorm Tools

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Clone and build the IceStorm toolset from source.

```bash
git clone https://github.com/YosysHQ/icestorm.git icestorm
cd icestorm
make -j$(nproc)
sudo make install
```

--------------------------------

### Install Yosys

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Clone and build the Yosys synthesis tool.

```bash
git clone https://github.com/YosysHQ/yosys.git yosys
cd yosys
make -j$(nproc)
sudo make install
```

--------------------------------

### Install NextPNR

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Clone and build the NextPNR place-and-route tool.

```bash
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
```

--------------------------------

### Install Arachne-PNR

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Clone and build the Arachne-PNR place-and-route tool.

```bash
git clone https://github.com/YosysHQ/arachne-pnr.git arachne-pnr
cd arachne-pnr
make -j$(nproc)
sudo make install
```

--------------------------------

### Install Prerequisites on Ubuntu 14.04

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Install build dependencies required for the toolchain on Ubuntu 14.04.

```bash
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
```

--------------------------------

### Initialize Project Icestorm Environment

Source: https://github.com/yosyshq/icestorm/blob/main/docs/README.md

Creates a Python virtual environment and installs project requirements using make.

```bash
python -m venv .venv
source .venv/bin/activate
make reqs
```

--------------------------------

### Install Prerequisites on Fedora 24

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Install build dependencies required for the toolchain on Fedora 24.

```bash
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
```

--------------------------------

### Install libftdi0 on OSX

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/notes_osx.md

Commands to install the required FTDI library using MacPorts or Homebrew.

```bash
port install libftdi0
```

```bash
brew install libftdi0
```

--------------------------------

### Cell configuration description

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Example output from the icebox_explain program describing the configuration of a logic tile.

```default
.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
```

--------------------------------

### Synthesize a design with icecube.sh

Source: https://github.com/yosyshq/icestorm/wiki/Adding-support-for-new-devices

Example of creating a simple Verilog top module and running the synthesis script for a specific iCE40 device.

```shell
$ cat demo.v 
module top(input A, B, C, D, output X, Y, Z);
  assign X = |{A, B, C, D};
  assign Y = &{A, B, C, D};
  assign Z = ^{A, B, C, D};
endmodule

$ ICEDEV=ul1k-cm36a bash icefuzz/icecube.sh demo.v
```

--------------------------------

### Configure iceprog Makefile for MacPorts

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/notes_osx.md

Update the Makefile to include paths for MacPorts installations located in /opt/local.

```default
LDLIBS = -L/usr/local/lib -L/opt/local/lib -lftdi -lm
CFLAGS = -MD -O0 -ggdb -Wall -std=c99 -I/usr/local/include -I/opt/local/include/
```

--------------------------------

### Bitstream ASCII representation

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Example output from the iceunpack program showing the bit configuration for a logic tile.

```default
.logic_tile 12 12
000000000000000000000000000000000000000000000000000000
000000000000000000000011010000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000001011000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000
000000000000000000000000001000001000010101010000000000
000000000000000000000000000101010000101010100000000000
```

--------------------------------

### Example error message from icepack

Source: https://github.com/yosyshq/icestorm/wiki/Adding-support-for-new-devices

The error message encountered when the target device is not yet supported by icepack/iceunpack.

```text
+ icefuzz/../icepack/iceunpack demo.bin demo.asc
Error: Failed to detect chip type.
```

--------------------------------

### Implement and Program iCE40 FPGA

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Execute the full synthesis, place-and-route, and programming flow for an iCEstick board.

```bash
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
```

--------------------------------

### Explain bitstream contents with icebox_explain

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Displays the internal fabric configuration and tile details from an .asc file.

```default
$ 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
```

--------------------------------

### Sample .glb debug output

Source: https://github.com/yosyshq/icestorm/wiki/Adding-support-for-new-devices

A snippet of the .glb file showing bit settings for a LogicTile, used for reverse-engineering device bitstreams.

```text
LogicTile_8_10

 (11 6)  (323 182)  (323 182)  routing T_6_11.sp4_h_r_11 <X> T_6_11.sp4_v_t_40
 (13 6)  (325 182)  (325 182)  routing T_6_11.sp4_h_r_11 <X> T_6_11.sp4_v_t_40
 (12 7)  (324 183)  (324 183)  routing T_6_11.sp4_h_r_11 <X> T_6_11.sp4_v_t_40
```

--------------------------------

### Verilog and PCF source files

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Simple Verilog module and corresponding physical constraint file for synthesis.

```default
// 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
```

--------------------------------

### Configure Udev Rules for FPGA Hardware

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Add a udev rule to allow non-privileged users to access Lattice FPGA hardware.

```bash
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0660", GROUP="plugdev", TAG+="uaccess"
```

--------------------------------

### Synthesis and bitstream generation commands

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Command line sequence to synthesize a design using Yosys, place and route with Arachne-PNR, and generate a binary bitstream with icepack.

```default
$ 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
```

--------------------------------

### Generate Timing Analysis Report

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Run timing analysis on a generated bitstream using the icetime utility.

```bash
icetime -tmd hx1k rot.asc
```

--------------------------------

### Decompile bitstream to Verilog with icebox_vlog

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Converts an .asc bitstream file into a Verilog module representation using a provided .pcf constraint file.

```default
$ 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
```

--------------------------------

### Manage FTDI Drivers on OSX

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/notes_osx.md

Commands to check for and unload the FTDI USB serial driver to allow iceprog to access the FPGA.

```default
kextstat | grep FTDIUSBSerialDriver
```

```default
sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
```

--------------------------------

### Cite Project IceStorm in BibTeX

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/overview.md

Use this BibTeX entry to cite Project IceStorm in academic papers and reports.

```default
@MISC{IceStorm,
    author = {Claire Wolf and Mathias Lasser},
    title = {Project IceStorm},
    howpublished = "\url{https://prjicestorm.readthedocs.io/}"
}
```

--------------------------------

### Switch Yosys Compiler to GCC

Source: https://github.com/yosyshq/icestorm/blob/main/docs/source/notes_osx.md

Modify the Yosys Makefile to use GCC instead of Clang to resolve missing tuple header errors.

```default
#CONFIG := clang
CONFIG := gcc
```

--------------------------------

### PLL Configuration Word Structure

Source: https://github.com/yosyshq/icestorm/wiki/iCE40-PLL-documentation

The bit layout for the 26-bit (or 27-bit for UP5k) configuration word used to program the PLL.

```text
[   26] ShiftReg[1]  (UP5k only)
[   25] FSEnet
[24:23] pllout1Sel
[   22] Source Clock (0=Pad, 1=Fabric)
[   21] ShiftReg[0]
[20:19] pllout2Sel
[18:17] delaymuxsel
[16:14] FILTER_RANGE
[13:11] DIVQ
[10: 4] DIVF
[ 3: 0] DIVR
```

--------------------------------

### PLL Dynamic Reconfiguration Signals

Source: https://github.com/yosyshq/icestorm/wiki/iCE40-PLL-documentation

The interface signals required for the dynamic reconfiguration port of the iCE40 PLL.

```verilog
output wire SDO,
input  wire SDI,
input  wire SCLK,
input  wire RESETB,
```
Tokens:
Raw