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

.SH NAME

libvirtex, virtex.h, readbitfile, readfileheader, readstreamheader, setmodelfromconfigsize, allocframes, readmainframes, setclbrange, getclb, getlut, getff, Bit, Frame, Model, *Col, *Sli, *Row, *Lut, LutFont \- functions and global variables to handle Virtex (and Spartan-II) FPGA bitstreams

.SH SYNOPSIS

.B #include <virtex.h>
.sp
.BI "char *readbitfile(char *" BitfileName ", int " Verbose ");"
.br
.BI "char *readfileheader(void);"
.br
.BI "char *readstreamheader(void);"
.br
.BI "char *setmodelfromconfigsize(void);"
.br
.BI "char *allocframes(void);"
.br
.BI "char *readmainframes(void);"
.sp
.BI "extern struct VirtexModel *Model;"
.sp
.BI "char *setclbrange(char *" Range ");"
.sp
.BI "extern int Bit;"
.br
.BI "extern int Frame;"
.br
.BI "extern int FirstCol, LastCol, Col;"
.br
.BI "extern int FirstSli, LastSli, Sli, BeginSli, EndSli;"
.br
.BI "extern int FirstRow, LastRow, Row;"
.br
.BI "extern int FirstLut, LastLut, Lut, BeginLut, EndLut;"
.sp
.BI "char *getclb(void);"
.br
.BI "char *getlut(void);"
.br
.BI "char *getff(void);"
.sp
.BI "extern uint 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, \fBreadfileheader\fP, \fBreadstreamheader\fP and
\fBreadmainframes\fP read in various parts of the FPGA bitstream into memory.
They use the auxillory functions \fBsetmodelfromconfigsize\fP and
\fBallocframes\fP to determine device type and allocate memory for its data.
The variable \fBModel\fP of type \fIstruct VirtexModel\fP (for definition read
\fBvirtex.h\fP) is set while in \fBsetmodelfromconfigsize\fP and is used by
various functions and user programs to be flexible on FPGA model dependant
sizes (such as how many CLBs there are).
.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
\fBchar *\fP\fIBitfileName\fP an normal filename, or \fINULL\fP if it should
read from \fIstdin\fP. 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, if something went wrong.
.PP
\fBsetclbrange\fP parses an string \fBchar *\fP\fIRange\fP and extracts from it
an range description for which \fICLBs\fP to process. 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). \fBsetclbrange\fP returns an \fInot-NULL\fP pointer,
pointing to an error message, if something went wrong.
.PP
\fBsetclbrange\fP as result of parsing will set these global variables:
.RS
\fBFirstCol\fP, \fBLastCol\fP,
\fBFirstSli\fP, \fBLastSli\fP, \fBBeginSli\fP, \fBEndSli\fP,
\fBFirstRow\fP, \fBLastRow\fP,
\fBFirstLut\fP, \fBLastLut\fP, \fBBeginLut\fP and \fBEndLut\fP
.RE
Of these the \fBFirst*\fP and \fBLast*\fP are set to the values needed to
control loops running the desired range by looping over \fB*Col\fP and inside
it \fB*Sli\fP or \fB*Row\fP and inside it \fB*Lut\fP, while \fBBegin*\fP and
\fBEnd*\fP are set to include or drop the very first and/or last iteration of
the inner loop. See \fBexamples\fP for code how write the intended loops.
.PP
\fBBit\fP, \fBFrame\fP, \fBCol\fP, \fBSli\fP, \fBRow\fP and \fBLut\fP are
provided as loop index variables for selecting where in the FPGA operations
are to happen. They are intended to be set by loops running on above
\fBFirst*\fP and \fBLast*\fP variables.
.PP
\fBgetclb\fP returns an \fIsingle configuration bit\fP specified by \fBBit\fP
and \fBFrame\fP, from the current \fICLB\fP specified by \fBCol\fP and
\fBRow\fP. It is 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).
.PP
\fBgetlut\fP and \fBgetff\fP return the \fIvalue\fP of the \fILUT\fP or
\fIFF\fP of the \fIlogic cell\fP specified by \fBCol\fP/\fBSli\fP and
\fBRow\fP/\fBLut\fP.
.PP
\fBLutFont\fP contains an 128 char ASCII font encoded in the exact same format
as \fBgetlut\fP returns \fILUTs\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 dependig on \fIBeVerbose\fP:
.PP
.RS
.nf
#include "virtex.h"
serror = readbitfile(BitfileName, BeVerbose);
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 \fIOptRange\fP:
.PP
.RS
.nf
#include "virtex.h"
serror = setclbrange(OptRange);
if (serror != NULL) {
  fprintf(stderr, "%s: %s\n", ProgName, serror);
  exit(1); }
.fi
.RE
.PP
To loop through the range set above by \fBsetclbrange\fP, this is the suggested
nested looping constructs, which can be nested within each other, in
\fBCol\fP/\fBSli\fP major or in \fBRow\fP/\fBLut\fP major counting:
.PP
.RS
.nf
#include "virtex.h"
/* interleave halves of CLBs (Sli) with CLBs (Col) */
for (Col = FirstCol; Col <= LastCol; Col++) {
  for (Sli = FirstSli; Sli <= LastSli; Sli++) {
    /* check if BeginSli/EndSli suppress first/last iteration */
    if (!(Col == FirstCol && Sli == SLIL && BeginSli == SLIR ||
          Col == LastCol  && Sli == SLIR && EndSli   == SLIL)) {
      do_something_with_specified_vertical_line_of_luts(); } } }

/* interleave halves of slices (Lut) with slices (Row) */
for (Row = FirstRow; Row <= LastRow; Row++) {
  for (Lut = FirstLut; Lut <= LastLut; Lut++) {
    /* check if BeginLut/EndLut suppress first/last iteration */
    if (!(Row == FirstRow && Lut == LUTF && BeginLut == LUTG ||
          Row == LastRow  && Lut == LUTG && EndLut   == LUTF)) {
      do_something_with_specified_horizontal_line_of_luts(); } } }
.fi
.RE
.PP
To access an \fILUT\fP and process it, together with its positional data,
code like this can be used (\fISLIR\fP and \fILUTG\fP are constants defined
in \fBvirtex.h\fP):
.PP
.RS
.nf
#include "virtex.h"
fprintf(Outfile,
        "Col: %3i, Sli: %1c, Row: %3i, LUT: %1c, Val: 0x%04x\n",
        Col, (Sli == SLIR) ? 'R' : 'L',
        Row, (Lut == LUTG) ? 'G' : 'F', getlut()); }
.fi
.RE

.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 allways
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/