.\" http://neil.franklin.ch/Projects/VirtexTools/libvirtex.3
.\" author Neil Franklin, last modification 2003.09.20
.\"
.TH LIBVIRTEX 3 "2003.08.01" "VirtexTools"

.SH NAME

.\" when adding new entry, update SOPAGES var in Makefile, so all .so are made
libvirtex, virtex.h, lutpos, lutval,
readbitfile(), readfileheader(), readstreamheader(), setmodelfromconfigsize(),
allocframes(), readmainframes(), readframe(), readpipeframe(),
readbramdframes(), readstreamtail(),
setlutrange(), firstsli(), lastsli(), nextsli(), prevsli(), isinslis()
firstlut(), lastlut(), nextlut(), prevlut(), isinluts(), getlutpos(),
getcenterbit(), getgclkbit(), getclbbit(), getiobnsbit(),
getiobwebit(), getcornerbit(), getbramcbit(), getdllbit(),
getbramdbit(), getbramdpadbit(),
getlut(), getff(), LutFont[]
\- library, header file, functions and global variables to handle Virtex (and
Spartan-II) FPGA bitstreams

.SH SYNOPSIS

.B #include <virtex.h>
.sp
.BI "typedef struct lutpos { int " Col "; char " Sli ";
.br
.BI "                        int " Row "; char " Lut "; } lutpos;"
.br
.BI "typedef ushort lutval;"
.sp
.BI "char *readbitfile(FILE *" BitfilePtr ", int " Verbose ");"
.br
.BI "char *readfileheader(void);"
.br
.BI "char *readstreamheader(void);"
.sp
.BI "char *setmodelfromconfigsize(void);"
.sp
.BI "char *allocframes(void);"
.br
.BI "char *readmainframes(void);"
.br
.BI "char *readframe(ulong *" Top ", ulong *" Middle ",
.br
.BI "                int " StepMiddle ", ulong *" Bottom ");"
.br
.BI "char *readpipeframe();"
.br
.BI "char *readbramdframes(void);"
.br
.BI "char *readstreamtail(void);"
.sp
.BI "char *setlutrange(char *" Range ");"
.sp
.BI "void firstsli(void);"
.br
.BI "void lastsli(void);"
.br
.BI "void nextsli(void);"
.br
.BI "void prevsli(void);"
.br
.BI "int isinslis(void);"
.sp
.BI "void firstlut(void);"
.br
.BI "void lastlut(void);"
.br
.BI "void nextlut(void);"
.br
.BI "void prevlut(void);"
.br
.BI "int isinluts(void);"
.sp
.BI "char *getlutpos(void);"
.sp
.BI "int getcenterbit(int " Frame ", int " Bit ");"
.br
.BI "int getgclkbit(int " Frame ", int " Bit ");"
.br
.BI "int getclbbit(int " Frame ", int " Bit ");"
.br
.BI "int getiobnsbit(int " Frame ", int " Bit ");"
.br
.BI "int getiobwebit(int " Frame ", int " Bit ");"
.br
.BI "int getcornerbit(int " Frame ", int " Bit ");"
.br
.BI "int getbramcbit(int " Frame ", int " Bit ");"
.br
.BI "int getdllbit(int " Frame ", int " Bit ");"
.br
.BI "int getbramdbit(int " Frame ", int " Bit ");"
.br
.BI "int getbramdpadbit(int " Frame ", int " Bit ");"
.sp
.BI "lutval getlut(void);"
.br
.BI "int getff(void);"
.sp
.BI "extern ushort LutFont[];"

.SH DESCRIPTION

The \fBlibvirtex\fP library is a set of functions and global variables to
handle and process the contents of an Xilinx \fIVirtex FPGA bitstream\fP (.bit
file). In addition there is also an header file virtex.h to help users use
this library.
.PP
The user can use various functions to read in a bitstream to process it.
.PP
\fBreadbitfile()\fP is the main reader control routine, that calls all the
following reader functions in the proper way.
.PP
\fBreadfileheader()\fP, \fBreadstreamheader()\fP, \fBreadmainframes()\fP,
\fBreadbramdframes()\fP and \fBreadstreamtail()\fP read in various parts of
the FPGA bitstream into memory. They use the auxillary functions
\fBsetmodelfromconfigsize()\fP, \fBallocframes()\fP and \fBreadframe()\fP to
determine device type, allocate memory for its data and to parse frame data
into memory.
.PP
The \fIuser\fP only needs to use \fBreadbitfile()\fP which calls all the others
in the right way and at the right time. It takes as first parameter
\fBFILE *\fP\fIBitfilePtr\fP which should point to an opened bitstream file,
positioned at the beginning. If the second parameter \fBint \fP\fIVerbose\fP is
set to anything other than \fI0\fP then \fBreadbitfile\fP will output running
info what it is doing to \fIstderr\fP. \fBreadbitfile\fP returns an
\fInot-NULL\fP pointer, pointing to an error message string, if something went
wrong.
.PP
\fBsetlutrange()\fP parses an string \fBchar *\fP\fIRange\fP and extracts from
it an range description for which \fILUTs\fP to process, into the internal
variables \fICol\fP/\fISli\fP (horizontal) and \fIRow\fP/\fILut\fP (vertical).
For the format of this string see the description of the \fB-r\fP option in
\fBvd\fP(\fI1\fP) or \fBvv\fP(\fI1\fP). \fBsetlutrange()\fP returns an
\fInot-NULL\fP pointer, pointing to an error message, if something went wrong.
.PP
\fBfirstsli()\fP, \fBnextsli()\fP, \fBisinslis()\fP or
.br
\fBlastsli()\fP, \fBprevsli()\fP, \fBisinslis()\fP for slices/horizontal and
.br
\fBfirstlut()\fP, \fBnextlut()\fP, \fBisinluts()\fP or
.br
\fBlastlut()\fP, \fBprevlut()\fP, \fBisinluts()\fP for LUTs/vertical
.br
are used to step the \fIcurrent\fP LUT position left/right (\fB*sli()\fP) or
up/downwards (\fB*lut()\fP) though the range set by \fBsetlutrange()\fP.
Use \fBnext/prev*()\fP twice when working on entire CLBs. See \fBexamples\fP
for code how write the intended loops.
.PP
\fBgetlutpos()\fP returns an pointer to an struct \fBlutpos\fP, describing the
\fIcurrent\fP LUT position we are working on, where members \fBCol\fP and
\fBRow\fP are \fIint\fP and \fBSli\fP is a character 'L' or 'R' and \fBLut\fP
is a character 'F' or 'G'. Second call overwrites the struct, so first must be
saved if still to be used later.
.PP
\fBgetcenterbit()\fP, \fBgetgclkbit()\fP, \fBgetclbbit()\fP,
\fBgetiobnsbit()\fP, \fBgetiobwebit()\fP, \fBgetcornerbit()\fP,
\fBgetbramcbit()\fP, \fBgetdllbit()\fP, \fBgetbramdbit()\fP and
\fBgetbramdpadbit()\fP return an \fIsingle configuration bit\fP, whose position
is specified by \fBFrame\fP and \fBBit\fP, from the \fIcurrent\fP LUT positions
\fBcenter\fP, \fBGCLK\fP, \fBCLB\fP, \fBIOB N/S\fP, \fBIOB W/E\fP,
\fBcorner\fP, \fBBRAM control\fP, \fBDLL\fP, \fBBRAM data\fP or \fBBRAM data
pad\fP associated with it. These are usually only used by more powerfull
functions, such as \fBgetlut()\fP and \fBgetff()\fP, but can also be used by
user programs that know about bit positions and their ranges (\fI#define\fPd
in \fBvirtex.h\fP), as done in the \fB\-e\fP "entire" modes of
\fBvd\fP(\fI1\fP) and \fBvv\fP(\fI1\fP).
.PP
\fBgetlut()\fP and \fBgetff()\fP return the \fIvalue\fP of the \fILUT\fP or
\fIFF\fP of the \fIcurrent LUT position\fP. \fBgetlut()\fP has its own data
type \fBlutval\fP for its return value (full space of an 16bit unsigned).
.PP
\fBLutFont[]\fP contains an 128 char ASCII font encoded in the exact same
format as \fBgetlut()\fP returns \fILUT values\fP. It can be used to letter
graphics using exactly the same space as one \fILUT\fP, from the same code that
displays the \fILUTs\fP.

.SH EXAMPLES

To read in an bitstream from the file whose name is stored in \fIBitfileName\fP
and be verbose depending on \fIVerbose\fP:
.PP
.RS
.nf
#include "virtex.h"
char *BitfileName = "our-design.bit";
FILE *Bitfile = fopen(BitfileName =, "rb");
int Verbose = 0;
char *serror = readbitfile(Bitfile, Verbose);
if (serror != NULL) {
  fprintf(stderr, "%s: %s\\n", ProgName, serror);
  exit(1); }
.fi
.RE
.PP
To set the range to that whose range string is stored in \fIRange\fP:
.PP
.RS
.nf
#include "virtex.h"
/* column 2, slice left, rows 0..17, both LUTs */
char *Range = "2L/0-17";
char *serror = setlutrange(Range);
if (serror != NULL) {
  fprintf(stderr, "%s: %s\\n", ProgName, serror);
  exit(1); }
.fi
.RE
.PP
To loop through the range set above by \fBsetlutrange\fP, this is the suggested
nested looping constructs, which can be nested within each other, in
\fBcolumn\fP+\fBslice\fP major or in \fBrow\fP+\fBLUT\fP major counting:
.PP
.RS
.nf
#include "virtex.h"

for (firstsli(); isinslis(); nextsli()) {
  do_something_with_specified_vertical_line_of_luts(); }

for (firstlut(); isinluts(); nextlut()) {
  do_something_with_specified_horizontal_line_of_luts(); }

for (firstsli(); isinslis(); nextsli()) {
  for (firstlut(); isinluts(); nextlut()) {
    do_something_with_specified_single_lut(); } }
.fi
.RE
.PP
Best examples is to look at the mostly relatively simple source code of
\fBvd\fP(\fI1\fP) and \fBvv\fP(\fI1\fP).

.SH SEE ALSO

\fBVirtexTools\fP(\fI7\fP), \fBvd\fP(\fI1\fP), \fBvv\fP(\fI1\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/