.\" http://neil.franklin.ch/Projects/VirtexTools/VirtexTools.7
.\" author Neil Franklin, last modification 2002.10.09
.\"
.TH VIRTEXTOOLS 7 "2002.10.09" "VirtexTools"

.SH NAME

VirtexTools - toolset for programming and debugging of Xilinx Virtex FPGAs

.SH TABLE OF CONTENTS

\- Introduction
.br
\- Installation
.br
\- How to use
.br
\- Description of functions
.br
\- Future Develpment

.SH INTRODUCTION

This is a library (\fBlibvirtex\fP and \fBvirtex.h\fP) and various programs
using this library (\fBvd\fP and \fBvv\fP), that together allow processing
(and later generating) of \fIXilinx Virtex\fP (and Spartan-II) FPGA bitstreams
(\fI.bit\fP files).
.PP
In the end this toolset should allow doing everything needed for simple FPGA
development, using only these open source / free software tools. No need for
vendor / commercial tools.
.PP
Due to the relative lack of information/documentation, this toolset initially
will only target \fIVirtex\fP (and the bitstream compatible Spartan-II) series.
Other series related to them (Virtex-E, Virtex-EM, Spartan-IIE) will regard
more research to use.
.PP
Even just supporting Virtex is going to need reverse-engineering of the bit
positions to implement all desired features. At least there exist Xilinx tools
(\fIJBits\fP) that can be used for this purpose.
.PP
Presently no reverse-engineering has yet been done. All existing tools are
still based on published information, the data sheets and application notes,
particularly \fIXAPP138\fP and \fIXAPP151\fP.

.SH INSTALLATION

For this best read the \fIINSTALL\fP file that comes with the distribution.
It can be found at:
.br
http://neil.franklin.ch/Projects/VirtexTools/INSTALL

.SH HOW TO USE

There exist 2 different levels at which you can use this toolset. As pure
\fIcommand line programs\fP, and lower down as \fIlibrary from C programs\fP
(which is what the command line tools do internally).
.PP
.B Command Line Programs
.PP
At the moment there are 2 of these, \fBvd\fP and \fBvv\fP. These can both be
used to show the contents of an FPGA. \fBvd\fP does an textual dump of (part
of) the contents of an FPGA, \fBvv\fP does an graphical view of the same.
.PP
Both if these tools have their own man pages, \fBvd\fP(\fI1\fP) and
\fBvv\fP(\fI1\fP), that detail their many options for selecting exactly
what you want to see and how you want it presented.
.PP
.B C Library
.PP
This library consists of 2 parts, the \fBlibvirtex\fP library file and the
\fBvirtex.h\fP header that allows you to use it. Using the library starts by
including \fBvirtex.h\fP and then using the \fBreadbitfile\fP function to
read in an bitstream and prepare it to be processed.
.PP
Both of these have an single man page \fBlibvirtex\fP(\fI3\fP) that details
the available function and how to use them. Also you may want to look at the
source code of \fBvd\fP or \fBvv\fP, as these both use \fBlibvirtex\fP.

.SH DESCRIPTION OF FUNTIONS

These can be found in the \fBvd\fP(\fI1\fP), \fBvv\fP(\fI1\fP) and
\fBlibvirtex\fP(\fI3\fP) man pages.

.SH FUTURE DEVELOPMENT

The present limitation of \fBvd\fP and \fBvv\fP, that they can only process
\fILUTs\fP/\fICLBs\fP, will be dropped, so that all elements of an FPGA can be
showed. This will also result in extension of \fBlibvirtex\fP to be able to
read in and extract from BRAM data.
.PP
Then an third tool \fBvm\fP will allow modification of an bitstream, controlled
by an ASCII file similar in format to what \fBvd\fP produces, initially only
modification of \fILUTs\fP and \fIBRAM\fP data. This will also result in
extension of \fBlibvirtex\fP to be able to modify the data read in, and write
the changed data out to an new file. There will also be an initially fairly
useless "generate data as if from empty file" and change that function.
.PP
As third step them I will use \fBvd\fP together with JBits to reverse engineer
the bit positions in the bitstream. This will result in extensions to all 3
tools allowing showing and modifying/generation of all details. After this it
will be able to generate an bitstream from scratch using just VirtexTools
.PP
Apart from this various auxillary tools are intended, see the README file for
an detailed list of tools and their features, at:
.br
http://neil.franklin.ch/Projects/VirtexTools/README

.SH SEE ALSO

\fBvd\fP(\fI1\fP), \fBvv\fP(\fI1\fP), \fBlibvirtex\fP(\fI3\fP)

.SH HISTORY

Desire to see more about what is going on in an FPGA. To work without always
getting frustrated. To make educating simpler. A detailled list of reasons
can be seen in:
.br
http://neil.franklin.ch/Projects/VirtexTools/FAQ

.SH WEBSITE

This project has a website at:
.br
http://neil.franklin.ch/Projects/VirtexTools/

.SH AUTHOR

neil@franklin.ch, http://neil.franklin.ch/