Clifford: A Free and Open Source Verilog-to-Bitstream Flow for iCE40 FPGAs

It's my very great pleasure to introduce
to you Clifford

who is going to talk about a very complex
topic I know very little about, but that's

probably gonna change now.

So please give a warm round of applause
for "A Free and Open Source

Verilog-to-Bitstream Flow for iCE40
FPGAs".

applause

Thank you.

I'm talking about a Free and Open Source
Verilog-to-bitstream flow for iCE40 FPGAs

and in particular that means I'm going to
talk about three projects,

because these three projects together form
this Free and Open Source Verilog to

bitstream flow for this kind of FPGA.

The project I'm gonna talk about,
Project IceStorm, is an effort

to reverse engineer and document the
bitstream format for iCE40 FPGAs

and in particular right now we support the
HX1K and HX8K FPGAs.

In theory we should also support the LP1K
and LP8K--

if there is such a one, I don't know--
FPGAs because they just have different

timings but the bitstream format is
absolutely identical.

From the IceStorm project we get the
documentation for the bitstreams

documentation in human-readable form as
well as in machine-readable form

so we can write other tools that do useful
things with this kind of devices

and also from Project IceStorm we have a
couple of tools that we can use to read

bitstream files for those FPGAs and
convert those bitstream files into

different formats and vice-versa.

The second project I'm going to talk about
is arachne-pnr. arachne-pnr is a

place-and-route tool for the iCE40 FPGAs
and it's based on the IceStorm

documentation, so I wrote the IceStorm
documentation and then I was lucky enough

to find someone, Cotton Seed is his name,
to write this arachne-pnr place-and-route

tool, based on the documentation I wrote.

The third project I'm going to talk about
is Yosys, and Yosys actually is kind of my

main project that I'm working on now for
a little bit over three years

Yosys is a huge project but simply said
it's a Verilog synthesis suite so when you

have hardware designs that are written in
Verilog you can use Yosys to synthesize

those designs to netlists for a variety of
different architectures and one of those

architectures is the iCE40 FPGA
architecture, but I also have support for

other FPGA series, there is support for
ASIC synthesis and there is also support

for various forms of verification flows
in Yosys and

I'm going to talk about this a little bit,
not very much, just a little bit.

And last but not least I'm going to talk
about the icoBOARD

the icoBOARD is a development board
featuring the iCE40 FPGA

and I'm also showing you a little demo and
that's this contraption here we are going

to use this at the end of the talk.

So this is the flow, the big overview for
the flow

you see, you start with Verilog sources
and the synthesis script

usually the synthesis script just reads
the Verilog files and then executes a few

macro commands that do everything that is
necessary to synthesize for the specified

target, and of course we are looking at
the iCE40 FPGA here in particular.

The output of Yosys in this case is a BLIF
file

BLIF is a very easy, very simple netlist
format, and it's one of many format that

Yosys supports as backends.

We've made some extensions to the BLIF
file format to enable the use of

additional attributes on cells and
parameters, which is quite useful when you

do for example FPGA synthesis and would
like to have the LUT configuration as part

of a cell instantiation with a kind of
parameter.

The we take this netlist in the BLIF file
and we pass it on to arachne-pnr, the

place-and-route tool written by Cotton
Seed

and we also give arachne-pnr a few
additional files, namely we give it a

physical constraints file that specifies
where each pin should go, where each input

or output of the design should go on the
device, to which pin it should map.

Optionally, you can also specify a place-
and-route script that tells arachne-pnr

what strategy it should follow and which
of its internal passes it should execute

and in what order.

The output of that is what I call an
IceStorm text file

this is already a very very low-level file
format, you will see a short example of

that, where you can see for each
individual tile, just an ASCII block of

zeros and ones and then, you know, in line
8, column 13, this bit has this or that

function.

And lastly, we pass this IceStorm text
file to icepack, and icepack is a very

simple tool that can convert this easy to
read text file into the binary

representation that must be passed to the
FPGA in order to use this design.

Yeah, so, let's look at the first of those
four projects at the first part of my talk

Project IceStorm.

First I think I should give you a little
overview over the iCE40 FPGA series

because the iCE40 FPGAs are not very
widely used, I mean, a lot of people use

these Xilinx devices or Altera devices,
but Lattice iCE40 is kind of niche.

So it's a family of small FPGAs, the
largest one has a little bit under

8000 LUTs, and the LUTs are small
4-input LUTs.

The FPGA itself is of course a kind of
grid of tiles and different kinds of tiles

there are logic tiles and those logic
tiles have 8 look-up tables and for

each of those look-up tables an optional
flip-flop and carry chain logic that you

can use optionally.

There are also RAM tiles for block memory.
They always come in pairs, there is always

the RAM bottom tile and the RAM top tile
and the bottom tile and the top tile

together, they form a 4 kilobit SRAM.

And of course there are I/O tiles of the
edges of this grid that connect to the

programmable I/O pins, but also provide
the infrastructure necessary to connect

the FPGA logic with other resources on
the chip like PLLs and global nets.

A nice thing about iCE40 FPGAs is that
they come in quite reasonable packages

so when you would like to make your own
boards, it can be quite a hassle to work

with ball grid arrays and stuff like that,
but the iCE40 FPGAs come in packages like

144-pin TQFP that you can even solder by
hand if you have to.

And all of their very cheap development
boards, available from Lattice directly

for this kind of FPGAs, the Lattice
iCEstick costs less than $25, so it's

really affordable for someone who just
would like to experiment with it and have

a quick go with it.

Also, if you would like to do some
low-level stuff and are afraid of maybe

breaking your dev board by fiddling with
the configuration bits manually, then it's

quite nice to have a dev board in this
price range where nothing is, yeah, where

you can simply replace it.

So in summary the FPGA looks a little bit
like that. We have this grid of PLBs,

Programmable Logic Blocks, these are the
logic tiles, we have some memory tiles

that span two rows, and we have the I/O
tiles on the edges, and then in the middle

of that slide, we have a more detailed
look into one of these logic tiles, that

we see, we have these 8 flip-flops, 8
carry chain elements, and 8 look-up tables

this is all blown up here so we can see it
in more detail, however this is still just

it's still missing stuff, for example,
there is a connection that goes directly

from one LUT output to the second LUT
input of the next look-up table in this

chain, bypassing the flip-flop.

At the bottom right you see this is the
iCEstick dev board that you can buy from

Lattice for under $25. I think it costs
$25 from Lattice, but on Mouser it's

under $25.

Good, so with Project IceStorm we had a
detailed look at these FPGAs and we

documented the bitstream format and we
wrote these low-level tools that can be

used to work with bitstreams, and we also
defined a very simple text file that can

be used to just specify each and every
individual bit in the configuration, and

on the right on this slide you see a
little excerpt of what this text file

looks like, so you have here logic tile
9 9 and these are of course the

coordinates and then you just have this
block of ones and zeros and then you can,

when you look up the documentation online
that we provided, then you can decipher

that and say, ok, this bit is set because
that's this function and this kind of

makes sense for what this configuration
does.

So with the IceStorm tools we can convert
between the text files

and the binary files and we can also do a
lot of other interesting stuff.

For example, we can take one of those text
files and convert it back into

a behavioral Verilog model and actually
when I released this feature

the first time I got quite some hate mail
from people who thought I'm want to steal

their IP or something.

You can also create timing netlists from
these bitstreams directly, however this

is under construction. It's almost done
but not quite yet.

The reason why we are doing things like
that always on this low level bitstream

format is because we can create these
files from our own flow but we can also

create it for the bitstream files
generated by Lattice's flow, so it's very

easy to verify if our interpretation of
the bitstream is correct, we just create

random Verilog designs, pass it through
the Lattice flow, then convert the output

back into something that is behavioral
Verilog, and then use something like the

formal verification features in Yosys to
check if the Verilog we started with and

the Verilog we got out at the end are
formally equivalent.

So, you can go to clifford.at/icestorm
and browse the documentation I wrote.

A little bit of warning here, it's a
reference, it's not like an

introductionary textbook, so if you don't
know anything about how FPGAs work

internally, it might be a hard read. Also
it's actually not very very structured,

unfortunately, but it's not very long,
it's just a few pages,

so my recommendation if you really would
like to know how these FPGAs work and what

each individual bit means, is to just read
the entire thing once and then you have

an overview, and for example, most of the
interconnect is explained on the page for

the logic tiles, and things like PLLss and
global nets are explained on the page that

cover the I/O tiles. But it's really small
and you can read it in maybe an hour

or two, so it's I think not so bad.

So, the things provided by project
IceStorm, besides the actual tool,

the documentation provided is written
documentation that gives you an overview,

then there is an auto-generated HTML
documentation that gives you the reference

what each bit exactly means, and there
is also and auto-generated ASCII that can

be used in other tools, like arachne-pnr,
to do something with these kinds of FPGAs.

We have a couple of screenshots from this
documentation

so on the lower left you have some of the
written documentation that covers

this is actually from the I/O tile and you
see the column buffer control bits that

are used for the global nets and stuff
like that is documented here.

Then the two screenshots with these
wonderfully colored tables, these are

the auto-generated HTML documentation
where we document the function of each

and every individual bit and most of them
in more than just one way so we have

in this case some matrices that can tell
us which nets can be connected to which

other nets and what bits are used for
that.

And here on the upper right you actually
see for one logic tile the entire

collection of bits we have reverse
engineered, so you see there are some

grey areas, and as far as I can tell it's
not the things that I have missed but

these bits are just not used.

I can't be sure, of course, but I didn't
manage to create any Verilog design that

would use those bits so I think it's a
pretty fair guess that they are

actually unused. And on the bottom right
you see a part of the interconnect

documentation and you can see things like
these interconnect lines are pairwise

crossed-out and stuff like that, so it
took us quite a while to figure out all

these details.

So that's Project IceStorm, that's the
low-level stuff and of course it's very

interesting to just see how the FPGA works
and to know what each and every individual

bit does, but this doesn't really give us
something that we can use for everyday

design work with FPGAs.

Part two, arachne-pnr, this is the
place-and-route tool that Cotton Seed

wrote. This now takes this BLIF netlist
and converts it into one of those

text files, so it performs essentially
these operations here, it instantiates

I/O cells and clock buffers, this is more
like a convenience feature, but it's

something that is quite useful for
place-and-route, low-level implementation

tools to do something like that. It packs
LUTs and carry logic and flip-flop

instances into iCE40 logic cells because
the architecture netlist has individual

lookup tables and carry logic blocks and
flip-flops and we need to figure out how

we can fit them in these logic cells.