.\" http://neil.franklin.ch/Projects/VirtexTools/vd.1
.\" author Neil Franklin, last modification 2002.10.15
.\"
.TH VD 1 "2002.10.15" "VirtexTools"

.SH NAME

vd \- VirtexDump, textual dump of Virtex bitstreams

.SH SYNOPSIS

.B vd
[\fI\-emzlsqvh\fP] [\fI\-r range\fP] [\fI\-t base\fP[\fIbyte\fP]]
[\fI\-o file\fP] [\fIbitfile\fP]

.SH DESCRIPTION

The \fBvd\fP (VirtexDump) program is a utility to dump the contents of an
Xilinx \fIVirtex FPGA bitstream\fP (.bit file) \fIbitfile\fP (default
\fIstdin\fP) as an text.
.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 dump of those internals
he is interested in.

.SH OPTIONS

.TP
.B \-e
entire element: dump 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 \-m
memory mode: LUTs are treated as LUT-RAMs, rows are merged to an single memory
and displayed rotated (bits horizontal, address vertical). Overrides \fI\-e\fP.
\fI\-s\fP and \fI\-q\fP have here the same effects as usual
.TP
.B \-mz
zigzag memory mode: LUTs are treated as LUT-RAM32s with bits 0/2/../n-2 in
first slice and bist 1/3/../n-1 in second slice
.TP
.B \-z
short for \fI\-mz\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 \-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 dump 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 dumped
.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 dumped
.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 \-t \fIbase\fP\fR[\fP\fIbyte\fP\fR]\fP
type of base: for memory output
.RS
.TP
.B base
output number base: bits are converted to numbers of this base:
\fBa\fP = \fIASCII\fP, \fBb\fP = \fIbinary\fP, \fBd\fP = \fIdecimal\fP,
\fBh\fP = \fIhex\fP, \fBo\fP = \fIoctal\fP (default \fBb\fP)
.TP
.B byte
byte width: number \fI1\fP to \fIword width\fP or \fBI\fP = \fIInt\fP =
\fIfull word width\fP, \fBC\fP = \fIChar\fP = \fI8\fP, \fBS\fP = \fIShort\fP =
\fI16\fP, \fBL\fP = \fILong\fP = \fI32\fP (default \fBI\fP, unless base is
\fBa\fP where width is \fBC\fP). \fBa\fP with less than 7 width is not allowed
(is senseless). \fBa\fP where word is not multiple of byte, last partial char
is dropped, as it is not usable, must be unused
.PP
Multiple usage of \fB\-t\fP overrides previous uses of \fB\-t\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 vd
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\-t\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 \fBvd\fP and then still overridden by
actual command line options in specific cases.

.SH EXAMPLES

.TP
.B vd pdp10.bit
dumps \fIfull\fP pdp10.bit FPGA, 48*2*32*2 LUTs, at 1 line per LUT
.TP
.B vd -r 12L pdp10.bit
dumps \fIone slice\fP of pdp10.bit, 32*2 LUTs and lines
.TP
.B vd -sr 4-7/12-17 pdp10.bit
dumps \fIrectangular section\fP of pdp10.bit, 4*2*6*2 LUTs and lines,
with \fIshort\fP decoration
.TP
.B vd -qr 3R/8G pdp10.bit
dumps \fIone single LUT\fP of pdp10.bit, one single line, \fIquiet\fP
decoration. Produces an single hex number
.TP
.B vd -er 3/8 pdp10.bit
dumps \fIone single CLB configuration\fP of pdp10.bit, as bit pattern
.TP
.B vd -er 3R/8G pdp10.bit
dumps \fIsame single CLB\fP of pdp10.bit, as -e ignores slice and LUT in range
.TP
.B vd -mr 2L/0-17 pdp10.bit
dumps \fI1 memory of 16 words of 2*18bits\fP width out of pdp10.bit
.TP
.B vd -mqr 2L/0-17 -t b3 pdp10.bit
dumps above memory out of pdp10.bit, as \fI3bit bytes in binary\fP and in
\fIquiet\fP decoration
.TP
.B vd -mzr 1/0-17 pdp10.bit
dumps \fI1 zigzag memory\fP of 32 words of 2*16bits width out of pdp10.bit
.TP
.B vd -mzsr 1/0-17 -t o9 pdp10.bit
dumps above zigzag memory out of pdp10.bit, as \fI9bit bytes in octal, in
\fIshort\fP decoration
.TP
.B vd -mzsrt 1/0-17 o9 pdp10.bit
different command for same as above, -t combined with -mzsr

.SH BUGS

Due to the simplistic way base conversion is implemented (\fIsprintf()\fP on an
\fIulong\fP variable) the \fIbyte\fP width in \fB\-t\fP option is not allowed
to be larger than \fI32\fP, unless \fItype\fP is binary (which requires no
conversion).
.PP
Due to the way \fIASCII\fP mode is implemented (only one character) it will
ignore any part of an byte \fIwider than 8/\fP\fBC\fP bits.

.SH SEE ALSO

\fBVirtexTools\fP(\fI7\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 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/