.\" http://neil.franklin.ch/Projects/VirtexTools/vv.1
.\" author Neil Franklin, last modification 2002.10.14
.\"
.TH VV 1 "2002.10.14" "VirtexTools"

.SH NAME

vv \- VirtexView, graphical view of Virtex bitstreams

.SH SYNOPSIS

.B vv
[\fI\-etflsqavh\fP] [\fI\-r range\fP] [\fI\-p colour\fP] [\fI\-z factor\fP]
[\fI\-o file\fP] [\fIbitfile\fP]

.SH DESCRIPTION

The \fBvv\fP (VirtexView) program is a utility to view the contents of an
Xilinx \fIVirtex FPGA bitstream\fP (.bit file) \fIbitfile\fP (default
\fIstdin\fP) as an graphic.
.PP
For this the user can select the \fIrange\fP processed and a wide selection
of \fIformating options\fP to get just the type of view of those internals
he is interested in.
.SH OPTIONS
.TP
.B \-e
entire element: view entire CLB configuration as an 48x18 bit pattern, not
just the LUTs. \fI\-s\fP and \fI\-q\fP have here the same effects as
usual, \fIslice\fP and \fILUT\fP letters in \fIrange\fP are ignored
.TP
.B \-et
true entire layout: 48x18 bit pattern spaced with 3 dummy lines per line to
become 48x72, which fits the actual 2x3 geometry of an CLB. This looks better
than using -z 1x4, which produces an "stretched" look
.TP
.B \-t
short for \fI\-et\fP
.TP
.B \-ef
folded entire layout: folded pairs of horizontal neighboring pixels to vertical
to become 24x36, giving also 2x3 format, at half size, but sacrifices placement
fidelity
.TP
.B \-f
short for \fI\-ef\fP
.TP
.B \-l
long decoration: is data with labels and addresses (default). Overrides
\fI\-s\fP and \fI\-q\fP
.TP
.B \-s
short decoration: is data with addresses, no labels. Overrides \fI\-l\fP and
\fI\-q\fP
.TP
.B \-q
quiet decoration: just data, no labels or addresses. Overrides \fI\-l\fP and
\fI\-s\fP
.TP
.B \-a
ASCII format: produce an ASCII graphic, using '.' for 0 and '1' for 1 bits
(default is a .ppm graphic, convertable/displayable with ImageMagick or netpbm)
.TP
.B \-v
verbose operation: send running activity report to \fIstderr\fP 
.TP
.B \-h
help: display an short help text, summarising this man page, then abort without
processing anything
.TP
.B \-r \fIspec\fP
restrict range: to view to only [\fIhorizontal\fP][\fI/vertical\fP] (default
\fIfull chip\fP), where:
.RS
.TP
.B horizontal
is [\fIleft\fP][\fI\-\fP[\fIright\fP]], such as \fI14\fP (only one) or
\fI7-\fP (to end) or \fI6-17\fP (range) or \fI-23\fP (from begin).
\fIleft\fP must be smaller than \fIright\fP else nothing is viewed
.TP
.B vertical
is [\fIbottom\fP][\fI\-\fP[\fItop\fP]], same examples as horizontal.
\fIbottom\fP must be smaller than \fItop\fP else nothing is viewed
.TP
.B left
and
.TP
.B right
are \fIcolumn\fP[\fIslice\fP], such as \fI14\fP or \fI5L\fP or \fI23R\fP.
.RS
.PP
Without \fIslice\fP both slices are of that \fIcolumn\fP are included.
.PP
\fBleft\fP with \fIR\fP and \fBright\fP with \fIL\fP simply restrict away
first and last \fIslice\fP.
.PP
\fBleft\fP with \fIL\fP and \fBright\fP with \fIR\fP (which would do
same as nothing) restrict to only \fIL\fP or \fIR\fP side \fIslices\fP
.RE
.TP
.B bottom
and
.TP
.B top
are \fIrow\fP[\fILUT\fP], such as \fI14\fP or \fI5F\fP or \fI23G\fP
.RS
.PP
Effect of the facultative \fIF\fP and \fIG\fP is identical to \fIL\fP and
\fIR\fP above
.RE
.TP
.B column
and
.TP
.B row
are numbers of \fI0\fP to \fIsize-1\fP (numbered from the left or bottom of
FPGA)
.TP
.B slice
is \fIL\fP (left = slice 1) or \fIR\fP (right = slice 0)
.TP
.B LUT
is \fIF\fP or \fIG\fP
.PP
Multiple usage of \fB\-r\fP overrides previous uses of \fB\-r\fP
.RE
.TP
.B \-p \fIcolour\fP
paint bitmap: with \fIcolour\fP. Colours are defined with format \fItRGB\fP,
multiple using one \fI\-p\fP option with all in one block
.RS
.TP
.B t
is the type of the colour to be set. \fIo\fP for ones, \fIz\fP for zeros,
\fIt\fP for decoration text foreground, \fIb\fP for text background,
\fIs\fP for horizontal and vertical separating lines
.TP
.B RGB
are the red green and blue colour components. Are each an octal digit 0-7,
last 3 digits are used, superfluous digits are ignored
.PP
Default is to show the data in cyan on blue, decorations white on gray, and
separators in black.
.PP
Multiple usage of \fB\-p\fP overrides previous uses of \fB\-p\fP
.RE
.TP
.B \-z \fIfactor\fP
zoom: each logical pixel to \fIfactor\fP physical pixels. Default is 2x2 for
normal LUTs mode and 1x1 for \fI\-e\fP entire modes. A single digit such as
'3' is expanded to 3x3. Maximal horizontal scaling factor is 13 due to .ppm
output formatting (max 13 pixels of 6 chars each fit in max 79 chars per line)
.RS
.PP
Multiple usage of \fB\-z\fP overrides previous uses of \fB\-z\fP
.RE
.TP
.B \-o \fIfile\fP
output file: send to file (default \fIstdout\fP)
.RS
.PP
Multiple usage of \fB\-o\fP overrides previous uses of \fB\-o\fP
.RE
.TP
.B \-c \-b \-i \-d \-g
these options are reserved for planned future expansions

.SH ARGUMENTS

If an argument remains after option processing, it is assumed to be an
\fIfile name\fP, of the bitfile to be processed. Else a bitstream is expected
to come from \fIstdin\fP.

.SH ENVIRONMENT AND CONFIG FILES

.B vv
uses no environment variables or config files.
.PP
All options that override alternative choices (\fI\-l\fP, \fI\-s\fP or
\fI\-q\fP) or previous use of themselves (\fI\-r\fP, \fI\-p\fP, \fI\-z\fP or
\fI\-o\fP) can be set to the users preferred state in an \fIshell alias\fP or
\fIshell function\fP which then calls \fBvv\fP and then still overridden by
actual command line options in specific cases.

.SH EXAMPLES

(The programs \fIdisplay\fP and \fIconvert\fP are from the ImageMagick toolset)
.TP
.B vv pdp10.bit | display
views \fIfull\fP pdp10.bit FPGA, 48*2*32*2 LUTs, as 32*2 lines of 48*2 LUTs
.TP
.B vv -r 12L pdp10.bit | display
views \fIone slice\fP of pdp10.bit, 32*2 LUTs beneath each other
.TP
.B vv -r /0F pdp10.bit | display
views \fIone half row \fP of pdp10.bit, 48*2 LUTs next to each other
.TP
.B vv -sr 4-7/12-17 pdp10.bit | convert - pdp10.png
views \fIrectangular section\fP of pdp10.bit, 4*2*6*2 LUTs as 6*2 x 4*2,
with \fIshort\fP decoration, and puts it into an .png file
.TP
.B vv -qr 3R/8G -p o777z000 pdp10.bit | display
views \fIone single LUT\fP of pdp10.bit, one time 4x4 pixels, \fIquiet\fP
decoration, coloured in black&white. Produces just 16 pixels
.TP
.B vv -er 3/8 pdp10.bit | display
views \fIone single CLB configuration\fP of pdp10.bit, as bit pattern 48x18
.TP
.B vv -er 3R/8G -o pdp10.3r8g.ppm pdp10.bit
views \fIsame single CLB\fP of pdp10.bit, as -e ignores slice and LUT in range,
and writes it out into file 3r8g.ppm
.TP
.B vv -er 3/8 -z 1x4 pdp10.bit | display
views \fIsame single CLB\fP of pdp10.bit, stretched 4* vertical, to 2x3 format
.TP
.B vv -erz 3R/8G 1x4 pdp10.bit | display
views \fIsame single CLB\fP of pdp10.bit, as above, -z combined into -er
.TP
.B vv -etr 3R/8G pdp10.bit | display
views \fIsame single CLB\fP of pdp10.bit, true layout, with empty lines
.TP
.B vv -efrz 3R/8G 2x2 pdp10.bit | display
views \fIsame single CLB\fP of pdp10.bit, folded layout, 2x2 zoomed pixels
.TP
.B vv -ar 0-12/0-17 pdp10.bit | less -S
views \fIrectangular section\fP of pdp10.bit, 13*2*17*2 LUTs as 13*2 x 17*2
times 4x4 character ASCII graphic and show it in less, without line wrapping

.SH BUGS

Due to the simplistic way font rendering is implemented (strict 4x4 pixels
before layouting) the vertical/left \fB\-l\fP decoration gets messed up when
layouting for the \fItrue\fP and \fIfolded\fP layouts. Ignore it or use
\fB\-s\fP or \fB\-q\fP decoration which have no vertical/left part.
.PP
Due to the simplistic way zooming is implemented (.ppm fits max 13 chars of 6
bytes in 79 char line) the \fIhorizontal zooming\fP is not allowed to be
larger than \fI13\fP.
.PP
Due to the large size of .ppm files/streams larger ranges (particularly when
zoomed) take quite a bit of time and use up disk space.

.SH SEE ALSO

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