• Updated 2023-07-12: Hello, Guest! Welcome back, and be sure to check out this follow-up post about our outage a week or so ago.

Bitstream viewer for Xilinx XC3-family FPGAs


Well-known member
I have put up a first version of my Xilinx XC3-family bitstream viewer online.

It is over here: XC3000 display

The source code can be found on Github over here.

What is this?

Screenshot 2024-03-22 at 22-15-37 XC3000 display.png
Screenshot 2024-03-23 at 10-08-44 XC3000 display.png

It is the tool I have been developing in my other thread, the one about the Lapis ProColorServer. It is built from Ken Shirriff's XC2064 bitstream viewer, however I've had to reverse-engineer the XC3-family bitstreams from the ground up.

Since I was told that there are other pieces of vintage hardware that use XC3-family FPGAs, I made it versatile. It should support the entire XC3 family, that is: XC3020, XC3030, XC3042, XC3064, XC3090, XC3120A, XC3130A, XC3142A, XC3164A, XC3190A, XC3195A.

This viewer supports both text format (.rbt files) and binary format bitstreams. It is able to find multiple bitstreams per file, and lets you select them. For example, the Carrera 040 file I was given contains two bitstreams, for a XC3020 and a XC3042. This is supported. You can also load something like the DeclROM from a Lapis ProColorServer, it will also show you all the bitstreams it contains.

This viewer will show you a gate-level view of the FPGA bitstream, showing the various functional blocks (CLBs, IOBs, etc) and the nets that connect them together. You can right-click a CLB or IOB to get a diagram depicting its configuration.

You may change the chip package for the current bitstream, this will change the labels on the IOBs, you will want these labels to match the physical pins on the FPGA you're working on.

View settings change the display. 'Show all interconnects' will show all the possible interconnect resources, it's quite a mess but it can be helpful to understand how the interconnects work. 'Debug view' shows the raw interconnect data: the interconnects and switch matrix 'wires', similarly to Shirriff's original viewer.

The repo also contains code for a FPGA emulator. I haven't really made an interface for it, so for now if you want to use the emulator you would have to get the code and put it up on a localhost and write your own code to use the emulation. There's code in emulator.js you may use as a reference.

Technical notes:

When building the nets, the viewer does a bunch of optimization: basically, suppressing unneeded inputs. Technically, most input muxes don't have a 'no input selected' position, so there is always one input interconnect active for each input. Production bitstreams will also typically have 'zero' nets that tie together all these unused inputs. I have seen atleast one instance where an (unused) output connects to a zero net, which obviously makes a mess.

How do we know when an input is unneeded? By looking at the functional block's configuration. For example, if a given IOB isn't configured as an output, we can ignore anything that connects to its O input. For CLBs, some inputs will have explicit enable bits, some will only be relevant if the flip-flops are used (like the clock input), some will only be relevant if the logic tables account for them. You get the idea.

The net optimization gets rid of all the unneeded mess, but obviously there are chances that it might backfire. And obviously we may also have bugs in the bitstream decoding itself.

So, I would like you to tell me if you run into any oddities while looking at bitstreams: missing inputs, nets that short eachother, nets that go all over the chip and connect to a billion things, or generally anything that doesn't seem to make sense.

Screenshot 2024-03-09 at 23-33-23 XC3000 display.png
An example of shorted nets. This one was caused by a decoding bug.


This is a first version of this viewer, and there's room for improvement. I am open to any suggestions, ideas, etc. about it.

There are a few related things I have in mind:
* building more human-readable documentation about the XC3-family bitstream format
* building some sort of netlist from the bitstream data
* backporting the improvements in this viewer to the XC2018 one