VirtexTools FPGA Programming and Debugging Tools Project

Project Basics

It is based on the information provided in the XAPP138 and XAPP151 application notes, that describe part of the bitstream format. Particularly they describe the file header and configuration frame formats, and the positions of the LUTs, FFs, BRAMs and IOB FFs. They also describe how to download configuration and read back chip status. In addition to that I will be using the JBits tools for "black box" reverse engineering of the configuration bitstream bit positions.

This project grow out of my PDP-10 Clone Microprocessor in FPGA project. Mainly from my frustration with the existing tool situation.

Intended tools are:

• underlying library for processing bitstreams (libvirtex), this is all that is needed, the rest is to use this easily
• bitstream LUT/BRAM textual dumper VirtexDump (vd)
• bitstream LUT/BRAM graphical viewer VirtexView (vv)
• bitstream LUT/BRAM modifier/generator VirtexModify (vm)
• bitstream routing integrity checker VirtexRouteChecker (vrc)
• assembly-like language to bitstream VirtexAssembler (vas)
• bitstream down- and uploader VirtexDownloader (vdl)
• LUT/FF/IOB/BRAM showing runner/debugger VirtexDebug (vdb)
• bitstream static timing analyser VirtexTimeanalyser (vta)
• (possibly) "object" file linker VirtexLinker (vld) together with object output support in vas
• (unlikely) bitstream graphical editor VirtexEdit (ved)

Intended usage of these tools (tool flow) is:

• users with high level design code use an 3rd party compiler to convert it to something that vas will understand, that involves converting language features into FPGA elements (LUTs, FFs, F5/6, carry chains) which are relatively placed, and connections
• users with vas source code (written by hand or 3rd party tool generated) use vas to convert it to an vm input file, converting relative placed LUTs to absolute placed ones, and routing connections into individual PIPs
• users with vm input files have vm process into bitstream files, which can be modifications of existing ones (adding LUT-RAM or BRAM content) or generating from scratch (new designs). vm is intended to be an dumb simple back end that just works on the bitstreams without getting in the way
• vv and vd can be used to look at the resulting bitstream, graphical overview with vv and textual details with vd
• vrc can be used to check for routing integrity (no PIP combinations that make 2 output drive each other to destruction)
• vta can be used to get an idea what speed the design will run at, and to pinpoint which signal paths are limiting this speed
• vdl and vdb can be used to run/debug the resulting bitstreams

Addendum 2003.12.24: This project and PDP-10 canceled on 2003.12.24. After 1 month of forced break (HD crash, system rebuild) and 1.5 months since then of doing nothing on either this project or on PDP-10, I have come the the conclusion that I have lost all interest in both of them. Reasons are many:

• Original reason for this project was my FPGA PDP-10 project, and wanting better tools (no Windows, no Java, open source) for doing that. Loss of interest in that project (partly because tool situation) destroyed this reason. See thats cancelation
• Reasons there also apply to any other FPGA CPU project, large or small. Emulation on modern CPUs (fast or small ones) beats own soft-CPUs in FPGA in all cases. Only interesting hardware project would be 74(x)xx+PAL parts or even own transistor modules, no FPGA
• Extending an emulator with real look&feel hardware, such as:
  • Front pannel, 12..36bit universal width (or even 12..18bit module with 32/32 as 2*16/18), to control emulated CPU and edit its memory. Could even control an debugger on emulator or even gdb derivate driving PC program. Already exists
  • vector display, square such as Type 30 (PDP-1, Spacewar) oder 4:3 TV Tube such as VR14 (PDP-8 or PDP-11). But is heavy analog high voltage stuff, not my interest. Simulating one of these with special driver to normal PC monitor is possible, but not really interesting, and also exists in software for SIMH emulator on PC display
  • recreating an terminal (own keyboard with non-PC keys and monitor with own non-PC bezel in own case). But easier find/save/use an original terminal, on RS232, as they are still fairly common
  And no use/need for FPGAs in any of these anyway, just 74(x)xx+PAL, or microcontrollers, or worst case CPLDs (with have same software problems as FPGAs)
• No other "needs FPGA, can not be done in software or 74(x)xx+PAL" project has arisen to make any FPGA activities or tools worthwhile
• Additionally Xilinxes "don't help open source, we see such tools as a threat to us" attitude results in too much time with drudge work, just to reverse engineer their chips and make VirtexTools, before even using them for an hardware project with its own drudge. This partially killed my PDP-10 project (by delaying until outdated). And I don't want to make the chips of an company that harmed my project like that in any way more attractive, so no software for their chips. Even I if still were doing anything needing commercial FPGAs I would use an different brand. So no use for continuing tools for Virtex anyway
• The same problem of closed bit formats and anti-opensource attitudes prevails at all vendors known to me. So all commercial FPGAs are not attractive parts for me or other open source people, for anything, because closed software attitudes and no open tools and single-source if there were tools. So make no tools for any of them
• Doing anything with FPGAs will require making an open source FPGA chip, or joining an existing SoG FPGA project on opencores. And making tools for that. But I have no FPGA interests anyway
• This site and all work done up until now remains online, in case someone wants to continue this project, copy "Current" and work on

Project Status

Done are:

• Read-in .bit file bitstreams (but without the BRAM data section)
• Process them to generate LUT and entire CLB output lists

• Process bitstream to generate LUT and entire CLB output pictures, which can then be commented for documentation

• Read-in BRAM data section from .bit file bitstreams

Doing is:

Todo are:

• Expansion of vd and vv to handle the entire FPGA, non-CLBs (but still targeting LUT and BRAM only)

• Write-out bitstreams, generate CRCs
• modify bits (LUTs and BRAMs only)
• generate an empty bitstream

• Reverse engineer the bit positions of features and PIPs using JBits and vd and put code in libvirtex. This is mainly preparatory for the next step. But at this time it will be first time possible to generate bitstreams from scratch using only open source software (this being my third intended use of this project). I expect 3rd party projects at making compilers to be possible from here on

• Extend vd and vm to show/generate/modify any features and PIPs. This will allow making bitstream without writing C code that calles libvirtex, but rather any language that can output textual input for vm

• Add Routing functions to libvirtex and vm, and have vd list them. Make vrc for testing for error in routing. This should simply make using writing programs easier, standard work of routing already done

• vas assembler as comfortable front end to vm. This should make work even more simple, allowing normal users to simply sketch out an design and have the computer do as much as possible automatically. See my present Java source of PDP-10 project for hints at the programming style I use today. vas is intended to be an less verbose improvement on this. From here on normal users can use this stuff. Writing vas source or using 3rd party compilers (which may target libvirtex, vm or vas)

Code Download

• Installation Guide
• entire project: VirtexTools.tar.gz Archive
• single files:
  • libvirtex C source file
  • libvirtex C header file
  • vd textual dumper C source file
  • vv graphical viewer C source file
  • Makefile for compiling/installling
  • project intro man page
  • vd textual dumper man page
  • vv graphical viewer man page
  • libvirtex man page
  • website logo Java source code

• Installation Guide
• entire project: VirtexTools-20021015.tar.gz Archive
• single files:
  • libvirtex C source file
  • libvirtex C header file
  • vd textual dumper C source file
  • vv graphical viewer C source file
  • Makefile for compiling/installling
  • project intro man page
  • vd textual dumper man page
  • vv graphical viewer man page
  • libvirtex man page
  • website logo Java source code

• Installation Guide
• entire project: VirtexTools-20020922.tar.gz Archive
• single files:
  • vd textual dumper C source file
  • compile script for vd.c (obsolete)
  • Makefile for compiling/installling
  • vd man page

Auxillary documents

ASCII art of Virtex CLB PIPs
list of Virtex BRAM PIPs
estimated config bits sizes for some PALs and FPGAs

This is a lecture about hardware, self making, programmable logic and open source hardware, I held at the LUGcamp 2003 (in German): LUGcamp 2003 Vortrag Hardware

This is a file I made while searchig for still unused command line option:

options, what is being used, for what, and where

Usenet discussions

My comp.arch.fpga archive
Spartan II vs. Virtex [Spartan-II are bitstream compatible with Virtex, so can use JBits]
Re: virtex shape [Discussion of shape of Virtex chip and CLBs on it]
Amplify experience, was: FPGA Express strikes again! Xilinx response [The first "we want open tools" discussion I got into, mentioned NeoCAD reverse engineering Xilinx]
JBits [The thread I learned of this tool, the inspiration for VirtexTools]
Xilinx Configuration Bitstream [Discussion of bitstream problematic, got me started writing down ideas for VirtexTools project]
download bitstream to FPGA [Discussion of .bit file format, is more than just XAPP151]
Linux download bitstream [w/ source] [Tool source for Linux, how to access IO ports]
Is there a full open-source synthesis path for any FPGA? [Once againt he bitstream secrecy problem, my question if different for V2 (as that has got encryption) got ignored]
Why can Xilinx sw be as good as Altera's sw? [Grieving about vendors tools, turns to open source tools, and to patent effects on no compatible FPGA clones]
What's in a bitstream? [And once again bitstream secrecy]
FPGA implementation in (V)HDL [Looking for an open FPGA architecture for research, pointers to multiple of them, all SoG style, my critique of this style]
Regarding XC6216 [Looking for data sheet for the open XC6216, ends in Discussion how to get an open bitstream, I present idea of open source VHDL or EDIF SRAM-FPGA-in-ASIC or chip "laser printer"]

Not Usenet, but also the same problems being discussed:

Opencores.org Forum: Free Place & Route [Also discusses the lack of open source tools, closed bitstreams, this project gets referred to in an follow up]
Mail side discussion which sprang from above, in it I collect all the lame excuses from Xilinx

External Stuff (Links)

Xilinx, obviously :-)
Xilinx JBits SDK
Xilinx Data Book
Virtex 2.5V FPGAs (XCV00)
Virtex-E 1.8V FPGAs (XCV00)
Virtex-E 1.8V Extended Memory FPGAs
Spartan-II Family FPGAs (XC2S00)
Spartan-IIE Family FPGAs (XC2S00E)
XAPP Application Notes
XAPP151, Virtex Series Configuration Architecture User Guide
FPGA Art Gallery, triggered the idea of doing VirtexView
Chip Shots Gallery, ideas for styling VirtexView output colouring
MPGA - Meta Programmable Gate Array (FPGA-in-FPGA design)
"Lab#5" contains an FPGA-in-FPGA design called SJSU Spartan S01
Opencores.org: Project: Embedded FPGA Core
Opencores.org: Project: CF Reconfigurable Computing Array

This page is by Neil Franklin, last modification 2003.12.25