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.